diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2f0b3b0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+tests/_output/
diff --git a/assets/private-media.css b/assets/private-media.css
new file mode 100644
index 0000000..edd8364
--- /dev/null
+++ b/assets/private-media.css
@@ -0,0 +1,59 @@
+/**
+ * Private Media — Styles.
+ *
+ * Lock icon overlay and status label styles for the media library.
+ */
+
+/* Lock icon overlay on private attachments in grid view */
+.private-media-lock {
+	position: absolute;
+	top: 8px;
+	right: 8px;
+	background: rgba( 0, 0, 0, 0.7 );
+	color: #fff;
+	border-radius: 50%;
+	width: 28px;
+	height: 28px;
+	line-height: 28px;
+	text-align: center;
+	font-size: 16px;
+	z-index: 10;
+	pointer-events: none;
+}
+
+/* Ensure attachment preview is positioned for overlay */
+.attachment-preview {
+	position: relative;
+}
+
+/* Status label in media details */
+.compat-field-private_media_status .field strong {
+	display: inline-block;
+	padding: 2px 8px;
+	border-radius: 3px;
+	font-size: 12px;
+}
+
+/* Visibility override dropdown */
+.private-media-override {
+	width: 100%;
+	max-width: 250px;
+}
+
+/* List table row action links */
+.row-actions .private_media_public a,
+.row-actions .private_media_private a,
+.row-actions .private_media_auto a {
+	cursor: pointer;
+}
+
+/* Bulk action confirmation page */
+.private-media-bulk-confirm .attachment-list {
+	margin: 10px 0;
+	padding: 0;
+	list-style: disc inside;
+}
+
+.private-media-bulk-confirm .attachment-list li {
+	padding: 3px 0;
+}
diff --git a/assets/private-media.js b/assets/private-media.js
new file mode 100644
index 0000000..a290fb7
--- /dev/null
+++ b/assets/private-media.js
@@ -0,0 +1,82 @@
+/**
+ * Private Media — Media Library UI.
+ *
+ * Extends the WordPress media modal to add visibility controls
+ * and lock icon overlays for private attachments.
+ */
+( function( $, wp ) {
+	'use strict';
+
+	if ( ! wp || ! wp.media ) {
+		return;
+	}
+
+	/**
+	 * Handle visibility dropdown changes via AJAX.
+	 */
+	$( document ).on( 'change', '.private-media-override', function() {
+		var $select = $( this );
+		var attachmentId = $select.data( 'attachment-id' );
+		var override = $select.val();
+
+		$.ajax( {
+			url: privateMedia.ajaxUrl,
+			type: 'POST',
+			data: {
+				action: 'private_media_set_visibility',
+				nonce: privateMedia.nonce,
+				attachment_id: attachmentId,
+				override: override
+			},
+			success: function( response ) {
+				if ( response.success ) {
+					// Update the status display.
+					var $status = $select.closest( '.attachment-details, .compat-field-private_media_override' )
+						.siblings( '.compat-field-private_media_status' )
+						.find( 'strong' );
+
+					if ( response.data.override === 'public' ) {
+						$status.text( 'Forced Public' );
+					} else if ( response.data.override === 'private' ) {
+						$status.text( 'Forced Private' );
+					} else {
+						$status.text( response.data.status === 'public' ? 'Public' : 'Private' );
+					}
+
+					// Refresh the attachment in the library if possible.
+					if ( wp.media.frame && wp.media.frame.library ) {
+						var attachment = wp.media.frame.library.get( attachmentId );
+						if ( attachment ) {
+							attachment.fetch();
+						}
+					}
+				}
+			}
+		} );
+	} );
+
+	/**
+	 * Add lock icon overlay to private attachments in grid view.
+	 */
+	if ( wp.media.view && wp.media.view.Attachment ) {
+		var OriginalAttachment = wp.media.view.Attachment;
+
+		wp.media.view.Attachment = OriginalAttachment.extend( {
+			render: function() {
+				OriginalAttachment.prototype.render.apply( this, arguments );
+
+				var status = this.model.get( 'status' );
+				this.$el.find( '.private-media-lock' ).remove();
+
+				if ( status === 'private' ) {
+					this.$el.find( '.attachment-preview' ).append(
+						'<span class="private-media-lock dashicons dashicons-lock" title="Private"></span>'
+					);
+				}
+
+				return this;
+			}
+		} );
+	}
+
+} )( jQuery, window.wp );
diff --git a/composer.json b/composer.json
index 3eb8f49..c81faa5 100644
--- a/composer.json
+++ b/composer.json
@@ -25,7 +25,17 @@
 		],
 		"files": [
 			"inc/namespace.php",
-			"inc/global_assets/namespace.php"
+			"inc/global_assets/namespace.php",
+			"inc/private_media/namespace.php",
+			"inc/private_media/visibility.php",
+			"inc/private_media/content_parser.php",
+			"inc/private_media/post_lifecycle.php",
+			"inc/private_media/sanitisation.php",
+			"inc/private_media/signed_urls.php",
+			"inc/private_media/ui.php",
+			"inc/private_media/site_icon.php",
+			"inc/private_media/query_compat.php",
+			"inc/private_media/cli.php"
 		]
 	},
 	"extra": {
diff --git a/docs/assets/private-media-bulk-actions.png b/docs/assets/private-media-bulk-actions.png
new file mode 100644
index 0000000..c68a4f7
Binary files /dev/null and b/docs/assets/private-media-bulk-actions.png differ
diff --git a/docs/assets/private-media-list.png b/docs/assets/private-media-list.png
new file mode 100644
index 0000000..aa14a89
Binary files /dev/null and b/docs/assets/private-media-list.png differ
diff --git a/docs/assets/private-media-row-actions.png b/docs/assets/private-media-row-actions.png
new file mode 100644
index 0000000..9b111fb
Binary files /dev/null and b/docs/assets/private-media-row-actions.png differ
diff --git a/docs/private-media.md b/docs/private-media.md
new file mode 100644
index 0000000..d3c8fe6
--- /dev/null
+++ b/docs/private-media.md
@@ -0,0 +1,228 @@
+# Private Media
+
+The Private Media feature makes uploaded media **private by default**. When you upload an image, video, PDF or any other file to
+the media library, it cannot be accessed by visitors via its direct URL. The file only becomes publicly accessible when it is used
+in published content, or when you choose to make it public manually.
+
+This prevents uploaded media from being discoverable or shareable before the content it belongs to has been published.
+
+Private Media is enabled by default for all sites except the Global Media Library site. It can be disabled via configuration:
+
+```json
+{
+    "extra": {
+        "altis": {
+            "modules": {
+                "media": {
+                    "private-media": false
+                }
+            }
+        }
+    }
+}
+```
+
+## How It Works
+
+### Uploads Are Private by Default
+
+When you upload a file to the media library it starts as private. Anyone trying to access the file via its direct URL will receive
+an access denied error. Under the hood, this is implemented by setting the file's S3 storage permissions to private.
+
+Private files are still fully available to logged-in users who can upload media (authors, editors and administrators). You can
+browse them in the media library, insert them into posts, and use them as featured images as normal.
+
+### Files Become Public When Content Is Published
+
+When you publish a post or page, all the media used in it automatically becomes publicly accessible:
+
+- Images, videos and files embedded in the content are detected.
+- The featured image (post thumbnail) is included.
+- The files' storage permissions are updated so they can be accessed by visitors.
+
+If the same file is used in more than one published post, it stays public until all of those posts are unpublished.
+
+### Files Return to Private When Content Is Unpublished
+
+When you move a published post back to draft, trash it, or otherwise unpublish it:
+
+- All files that were referenced by that post are re-evaluated.
+- If a file is no longer used by any published post (and you haven't manually set it to public), it returns to private.
+
+The same re-evaluation happens when you edit a published post and remove an image from its content.
+
+## What You See in the Media Library
+
+### The Visibility Column
+
+The media library list view includes a **Visibility** column that shows the current access status of each file:
+
+![Media library list view showing the Visibility column](./assets/private-media-list.png)
+
+The possible statuses are:
+
+- **Private** — the default. The file cannot be accessed via its direct URL.
+- **Public** — the file is used in published content and can be accessed by visitors.
+- **Public (forced)** — you have manually set this file to always be public, regardless of whether it is used in published content.
+- **Private (forced)** — you have manually set this file to always be private, even if it is used in published content.
+
+### Changing Visibility with Quick Actions
+
+Hover over any file in the media library list to see the available quick actions:
+
+![Media library row actions showing Make Public and Make Private links](./assets/private-media-row-actions.png)
+
+- **Make Public** — makes the file publicly accessible, even if it is not used in any published content.
+- **Make Private** — makes the file private, even if it is currently used in published content.
+- **Remove Override** — removes your manual setting and returns the file to automatic management (appears after you have used Make
+  Public or Make Private).
+
+<!-- TODO: Add screenshot of success notice after changing visibility (assets/private-media-notice.png) -->
+
+### Changing Visibility for Multiple Files
+
+To change the visibility of several files at once:
+
+1. Select the files using the checkboxes in the media library list.
+2. Choose **Set Visibility** from the **Bulk actions** dropdown.
+3. Click **Apply**.
+4. On the confirmation screen, choose the target visibility and click **Apply**.
+
+<!-- TODO: Add screenshot of the bulk action confirmation screen (assets/private-media-bulk-confirm.png) -->
+
+### Changing Visibility in the Media Editor
+
+When editing a post, click on a file in the media browser to see its details in the sidebar. The **Visibility Override** dropdown
+lets you change the visibility setting directly without leaving the editor.
+
+<!-- TODO: Add screenshot of the media modal sidebar showing visibility dropdown (assets/private-media-modal-sidebar.png) -->
+
+The sidebar also shows:
+
+- The current access status of the file.
+- Which published posts are using the file (if any).
+- Whether the file is a legacy (pre-migration) upload.
+
+## Managing Post Attachments
+
+Posts and pages in the admin list include two additional quick actions for working with their media:
+
+- **Publish image(s)** — scans the post content and ensures all files used in it are publicly accessible. Useful if images appear
+  broken after a migration or configuration change.
+- **Unpublish image(s)** — removes the post's association with its files, which may cause them to become private if no other
+  published posts use them.
+
+<!-- TODO: Add screenshot of post list row actions showing Publish/Unpublish image(s) (assets/private-media-post-actions.png) -->
+
+## Previewing Draft Content
+
+When you preview a draft post, private images in the content are displayed using temporary signed URLs that expire after a short
+period. This means you can see exactly how the post will look without needing to make the images public first.
+
+## Existing Uploads and Migration
+
+When Private Media is first enabled on a site that already has uploaded files, all existing files remain publicly accessible. They
+are marked as "legacy" uploads so they continue to work without disruption.
+
+To apply this marking, run the migration command after enabling the feature:
+
+```
+wp private-media migrate
+```
+
+Use `--dry-run` to preview what would change without making any modifications.
+
+## Site Icon
+
+The site icon (favicon) is always treated as public, since it needs to be accessible on every page. This applies automatically
+when you set a site icon in **Settings > General**. If you specifically force the site icon to private, that override takes
+precedence.
+
+## Configuration
+
+### Disabling the Feature
+
+Set `private-media` to `false` in your Altis configuration to disable the feature entirely. When disabled, a compatibility layer
+remains active to ensure any files that were previously set to private status are still included in media queries, preventing
+them from disappearing.
+
+### Adding Custom Post Types
+
+By default, all post types that support the content editor are tracked for media references. If you have a custom post type that
+uses media but does not register editor support, you can include it:
+
+```php
+add_filter( 'private_media/allowed_post_types', function ( array $types ) : array {
+    $types[] = 'my_custom_type';
+    return $types;
+} );
+```
+
+### Registering Custom Image Fields
+
+If your theme or plugin stores file IDs in custom fields (similar to how WordPress stores the featured image), you can register
+those field names so they are included when scanning a post for media references:
+
+```php
+add_filter( 'private_media/post_meta_attachment_keys', function ( array $keys ) : array {
+    $keys[] = '_custom_header_image_id';
+    $keys[] = '_secondary_image_id';
+    return $keys;
+} );
+```
+
+### Adding Custom Media Sources
+
+For more advanced cases where files are associated with posts through non-standard means, you can add additional file IDs to the
+scan results:
+
+```php
+add_filter( 'private_media/post_attachment_ids', function ( array $ids, WP_Post $post ) : array {
+    // Include files from a custom gallery field.
+    $gallery_ids = get_post_meta( $post->ID, '_gallery_images', true );
+    if ( is_array( $gallery_ids ) ) {
+        $ids = array_merge( $ids, $gallery_ids );
+    }
+    return $ids;
+}, 10, 2 );
+```
+
+## WP-CLI Commands
+
+The following commands are available for managing private media from the command line. All commands support `--dry-run` to preview
+changes without applying them.
+
+### Migrate Existing Uploads
+
+```
+wp private-media migrate [--dry-run]
+```
+
+Marks all existing uploads as legacy (public) and ensures their status is correct. Run this when first enabling Private Media on a
+site with existing content.
+
+### Set Visibility for a Specific File
+
+```
+wp private-media set-visibility <public|private> <id|filename> [--dry-run]
+```
+
+Manually set the visibility for a specific file by its ID or filename.
+
+### Fix Inconsistencies
+
+```
+wp private-media fix-attachments [--start-date=<date>] [--end-date=<date>] [--dry-run] [--verbose]
+```
+
+Re-evaluates the visibility of all files, correcting any inconsistencies. Supports date range filtering for targeted fixes.
+
+## Hooks and Filters Reference
+
+| Filter                                    | Description                                                               |
+|-------------------------------------------|---------------------------------------------------------------------------|
+| `private_media/allowed_post_types`        | Array of post types to track for media references.                        |
+| `private_media/post_meta_attachment_keys` | Array of field names that store file IDs (like the featured image field). |
+| `private_media/post_attachment_ids`       | Array of file IDs found in a post. Receives `$ids` and `$post`.           |
+| `private_media/update_s3_acl`             | Intercept storage permission updates. Return non-null to short-circuit.   |
+| `private_media/purge_cdn_cache`           | Intercept CDN cache clearing. Return non-null to short-circuit.           |
diff --git a/docs/readme.md b/docs/readme.md
index 448c8e2..522a7d7 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -6,4 +6,7 @@ The Media module includes features and enhancements related to uploaded media. T
 includes [lazy loading](./lazy-loading.md), [AI powered image classification](./image-recognition.md)
 plus [dynamic image manipulation](./dynamic-images.md) and cropping tools.
 
+The module also provides [private media](./private-media.md) support, making uploaded attachments private by default and only
+publicly accessible when used in published content.
+
 In addition to the above features there are low-level enhancements including SVG sanitization to mitigate XSS attacks.
diff --git a/inc/namespace.php b/inc/namespace.php
index 39a834b..2fae03c 100644
--- a/inc/namespace.php
+++ b/inc/namespace.php
@@ -28,6 +28,9 @@ function bootstrap() {
 
 	// Set up global asset management.
 	Global_Assets\bootstrap();
+
+	// Set up private media feature.
+	Private_Media\bootstrap();
 }
 
 /**
diff --git a/inc/private_media/class-cli-command.php b/inc/private_media/class-cli-command.php
new file mode 100644
index 0000000..59fbb54
--- /dev/null
+++ b/inc/private_media/class-cli-command.php
@@ -0,0 +1,293 @@
+<?php
+/**
+ * Private Media — WP-CLI Command.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media;
+
+use Altis\Media\Private_Media\Visibility;
+use Altis\Media\Private_Media\Post_Lifecycle;
+use WP_CLI;
+use WP_CLI\Utils;
+use WP_Query;
+
+/**
+ * Manage private media visibility.
+ */
+class CLI_Command extends \WP_CLI_Command {
+
+	/**
+	 * Migrate existing attachments for private media support.
+	 *
+	 * Marks all existing attachments as legacy and sets their post_status to 'publish'.
+	 * This ensures existing content continues to work after enabling the feature.
+	 *
+	 * ## OPTIONS
+	 *
+	 * [--dry-run]
+	 * : Preview changes without applying them.
+	 *
+	 * @param array $args       Positional arguments.
+	 * @param array $assoc_args Associative arguments.
+	 * @return void
+	 */
+	public function migrate( array $args, array $assoc_args ) : void {
+		$dry_run = Utils\get_flag_value( $assoc_args, 'dry-run', false );
+
+		if ( $dry_run ) {
+			WP_CLI::log( 'Dry run mode — no changes will be made.' );
+		}
+
+		$query = new WP_Query( [
+			'post_type'      => 'attachment',
+			'post_status'    => [ 'inherit', 'private' ],
+			'posts_per_page' => 100,
+			'paged'          => 1,
+			'fields'         => 'ids',
+			'no_found_rows'  => false,
+		] );
+
+		$total = $query->found_posts;
+		$processed = 0;
+
+		WP_CLI::log( sprintf( 'Found %d attachments to migrate.', $total ) );
+
+		$progress = Utils\make_progress_bar( 'Migrating attachments', $total );
+
+		while ( $query->have_posts() ) {
+			foreach ( $query->posts as $attachment_id ) {
+				$metadata = wp_get_attachment_metadata( $attachment_id );
+				if ( ! is_array( $metadata ) ) {
+					$metadata = [];
+				}
+
+				if ( ! $dry_run ) {
+					$metadata['legacy_attachment'] = true;
+					wp_update_attachment_metadata( $attachment_id, $metadata );
+
+					wp_update_post( [
+						'ID'          => $attachment_id,
+						'post_status' => 'publish',
+					] );
+
+					Visibility\update_s3_acl( $attachment_id, 'public-read' );
+				}
+
+				$processed++;
+				$progress->tick();
+			}
+
+			// Next page.
+			$query = new WP_Query( [
+				'post_type'      => 'attachment',
+				'post_status'    => [ 'inherit', 'private' ],
+				'posts_per_page' => 100,
+				'paged'          => 1,
+				'fields'         => 'ids',
+				'no_found_rows'  => false,
+			] );
+
+			if ( empty( $query->posts ) ) {
+				break;
+			}
+		}
+
+		$progress->finish();
+		WP_CLI::success( sprintf( '%d attachments %s.', $processed, $dry_run ? 'would be migrated' : 'migrated' ) );
+	}
+
+	/**
+	 * Set the visibility of a specific attachment.
+	 *
+	 * ## OPTIONS
+	 *
+	 * <visibility>
+	 * : The visibility to set. 'public' or 'private'.
+	 *
+	 * <id>
+	 * : The attachment ID or filename.
+	 *
+	 * [--dry-run]
+	 * : Preview changes without applying them.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     wp private-media set-visibility public 123
+	 *     wp private-media set-visibility private my-image.jpg --dry-run
+	 *
+	 * @param array $args       Positional arguments.
+	 * @param array $assoc_args Associative arguments.
+	 * @return void
+	 */
+	public function set_visibility( array $args, array $assoc_args ) : void { // phpcs:ignore HM.Functions.NamespacedFunctions
+		$visibility = $args[0];
+		$identifier = $args[1];
+		$dry_run = Utils\get_flag_value( $assoc_args, 'dry-run', false );
+
+		if ( ! in_array( $visibility, [ 'public', 'private' ], true ) ) {
+			WP_CLI::error( 'Visibility must be "public" or "private".' );
+		}
+
+		// Resolve attachment ID from filename or ID.
+		$attachment_id = $this->resolve_attachment_id( $identifier );
+
+		if ( ! $attachment_id ) {
+			WP_CLI::error( sprintf( 'Attachment not found: %s', $identifier ) );
+		}
+
+		$post = get_post( $attachment_id );
+		if ( ! $post || $post->post_type !== 'attachment' ) {
+			WP_CLI::error( sprintf( 'ID %d is not an attachment.', $attachment_id ) );
+		}
+
+		WP_CLI::log( sprintf(
+			'Setting attachment %d (%s) to %s.',
+			$attachment_id,
+			$post->post_title,
+			$visibility
+		) );
+
+		if ( ! $dry_run ) {
+			Visibility\set_override( $attachment_id, $visibility );
+		}
+
+		WP_CLI::success( $dry_run ? 'Would update attachment.' : 'Attachment updated.' );
+	}
+
+	/**
+	 * Fix attachment visibility for published posts in a date range.
+	 *
+	 * Scans published posts and re-evaluates all their attachments.
+	 *
+	 * ## OPTIONS
+	 *
+	 * [--start-date=<date>]
+	 * : Start date (Y-m-d). Defaults to 30 days ago.
+	 *
+	 * [--end-date=<date>]
+	 * : End date (Y-m-d). Defaults to today.
+	 *
+	 * [--dry-run]
+	 * : Preview changes without applying them.
+	 *
+	 * [--verbose]
+	 * : Show detailed output for each post.
+	 *
+	 * @param array $args       Positional arguments.
+	 * @param array $assoc_args Associative arguments.
+	 * @return void
+	 */
+	public function fix_attachments( array $args, array $assoc_args ) : void { // phpcs:ignore HM.Functions.NamespacedFunctions
+		$start_date = Utils\get_flag_value( $assoc_args, 'start-date', gmdate( 'Y-m-d', strtotime( '-30 days' ) ) );
+		$end_date = Utils\get_flag_value( $assoc_args, 'end-date', gmdate( 'Y-m-d' ) );
+		$dry_run = Utils\get_flag_value( $assoc_args, 'dry-run', false );
+		$verbose = Utils\get_flag_value( $assoc_args, 'verbose', false );
+
+		if ( $dry_run ) {
+			WP_CLI::log( 'Dry run mode — no changes will be made.' );
+		}
+
+		$post_types = Post_Lifecycle\is_allowed_post_type( 'post' ) ? get_post_types_by_support( 'editor' ) : [];
+		if ( empty( $post_types ) ) {
+			$post_types = [ 'post', 'page' ];
+		}
+
+		$query = new WP_Query( [
+			'post_type'      => $post_types,
+			'post_status'    => 'publish',
+			'date_query'     => [
+				[
+					'after'     => $start_date,
+					'before'    => $end_date,
+					'inclusive' => true,
+				],
+			],
+			'posts_per_page' => 50,
+			'paged'          => 1,
+			'no_found_rows'  => false,
+		] );
+
+		$total = $query->found_posts;
+		WP_CLI::log( sprintf( 'Found %d published posts in date range %s to %s.', $total, $start_date, $end_date ) );
+
+		$progress = Utils\make_progress_bar( 'Fixing attachments', $total );
+		$fixed = 0;
+		$page = 1;
+
+		while ( $query->have_posts() ) {
+			foreach ( $query->posts as $post ) {
+				$attachment_ids = Post_Lifecycle\get_post_attachment_ids( $post );
+
+				if ( $verbose ) {
+					WP_CLI::log( sprintf(
+						'Post %d (%s): %d attachments found.',
+						$post->ID,
+						$post->post_title,
+						count( $attachment_ids )
+					) );
+				}
+
+				foreach ( $attachment_ids as $attachment_id ) {
+					if ( ! $dry_run ) {
+						Visibility\add_post_reference( $attachment_id, $post->ID );
+						Visibility\set_attachment_visibility( $attachment_id );
+					}
+					$fixed++;
+				}
+
+				if ( ! $dry_run ) {
+					update_post_meta( $post->ID, 'altis_private_media_post', $attachment_ids );
+				}
+
+				$progress->tick();
+			}
+
+			$page++;
+			$query = new WP_Query( [
+				'post_type'      => $post_types,
+				'post_status'    => 'publish',
+				'date_query'     => [
+					[
+						'after'     => $start_date,
+						'before'    => $end_date,
+						'inclusive' => true,
+					],
+				],
+				'posts_per_page' => 50,
+				'paged'          => $page,
+				'no_found_rows'  => false,
+			] );
+		}
+
+		$progress->finish();
+		WP_CLI::success( sprintf(
+			'%d attachment references %s across %d posts.',
+			$fixed,
+			$dry_run ? 'would be fixed' : 'fixed',
+			$total
+		) );
+	}
+
+	/**
+	 * Resolve an attachment ID from an ID number or filename.
+	 *
+	 * @param string $identifier The attachment ID or filename.
+	 * @return int|null The attachment ID, or null if not found.
+	 */
+	private function resolve_attachment_id( string $identifier ) : ?int {
+		if ( is_numeric( $identifier ) ) {
+			return (int) $identifier;
+		}
+
+		// Search by filename.
+		global $wpdb;
+		$attachment_id = $wpdb->get_var( $wpdb->prepare(
+			"SELECT post_id FROM {$wpdb->postmeta} WHERE meta_key = '_wp_attached_file' AND meta_value LIKE %s LIMIT 1",
+			'%' . $wpdb->esc_like( $identifier )
+		) );
+
+		return $attachment_id ? (int) $attachment_id : null;
+	}
+}
diff --git a/inc/private_media/cli.php b/inc/private_media/cli.php
new file mode 100644
index 0000000..90710fa
--- /dev/null
+++ b/inc/private_media/cli.php
@@ -0,0 +1,17 @@
+<?php
+/**
+ * Private Media — CLI Command Registration.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\CLI;
+
+/**
+ * Bootstrap CLI commands.
+ *
+ * @return void
+ */
+function bootstrap() {
+	\WP_CLI::add_command( 'private-media', '\\Altis\\Media\\Private_Media\\CLI_Command' );
+}
diff --git a/inc/private_media/content_parser.php b/inc/private_media/content_parser.php
new file mode 100644
index 0000000..7dd0b5f
--- /dev/null
+++ b/inc/private_media/content_parser.php
@@ -0,0 +1,167 @@
+<?php
+/**
+ * Private Media — Content Parser.
+ *
+ * Pure functions that extract attachment IDs and URLs from post content.
+ * No side effects — used by post_lifecycle.php and other consumers.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Content_Parser;
+
+/**
+ * Extract attachments from post content.
+ *
+ * Returns an array of arrays, each containing:
+ * - attachment_id (int)
+ * - attachment_url (string) — cleaned base URL
+ * - modified_url (string) — URL as it appears in content
+ *
+ * @param string $content The post content to parse.
+ * @return array[] Array of [ attachment_id, attachment_url, modified_url ] arrays.
+ */
+function extract_attachments_from_content( string $content ) : array {
+	if ( empty( $content ) ) {
+		return [];
+	}
+
+	$results = [];
+
+	// 1. Standard <img> tags with wp-image-{id} class.
+	// Matches class="...wp-image-123..." and extracts the src attribute.
+	if ( preg_match_all( '/class="[^"]*wp-image-(\d+)[^"]*"[^>]*src="([^"]+)"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $match[2] ),
+				'modified_url'  => $match[2],
+			];
+		}
+	}
+
+	// Also match src before class.
+	if ( preg_match_all( '/src="([^"]+)"[^>]*class="[^"]*wp-image-(\d+)[^"]*"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[2],
+				'attachment_url' => clean_url( $match[1] ),
+				'modified_url'  => $match[1],
+			];
+		}
+	}
+
+	// 2. <img> tags with data-full-url attribute (and wp-image class).
+	if ( preg_match_all( '/class="[^"]*wp-image-(\d+)[^"]*"[^>]*data-full-url="([^"]+)"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $match[2] ),
+				'modified_url'  => $match[2],
+			];
+		}
+	}
+
+	// 3. Gutenberg block attributes: "imageUrl":"...","imageId":N
+	if ( preg_match_all( '/"imageUrl"\s*:\s*"([^"]+)"\s*,\s*"imageId"\s*:\s*(\d+)/', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$url = wp_unslash( $match[1] );
+			$results[] = [
+				'attachment_id' => (int) $match[2],
+				'attachment_url' => clean_url( $url ),
+				'modified_url'  => $url,
+			];
+		}
+	}
+
+	// 4. Gutenberg block attributes: "id":N,"src":"..." (e.g. video/file blocks).
+	if ( preg_match_all( '/"id"\s*:\s*(\d+)\s*,\s*"src"\s*:\s*"([^"]+)"/', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$url = wp_unslash( $match[2] );
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $url ),
+				'modified_url'  => $url,
+			];
+		}
+	}
+
+	// 5. Video blocks: <!-- wp:video {"id":N} --> with <video src="...">
+	if ( preg_match_all( '/<!--\s*wp:video\s+\{[^}]*"id"\s*:\s*(\d+)[^}]*\}\s*-->.*?(?:src|data-src)="([^"]+)"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $match[2] ),
+				'modified_url'  => $match[2],
+			];
+		}
+	}
+
+	// 6. File blocks: wp-file-{id} class — href may be on a child element.
+	if ( preg_match_all( '/class="[^"]*wp-file-(\d+)[^"]*".*?href="([^"]+)"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $match[2] ),
+				'modified_url'  => $match[2],
+			];
+		}
+	}
+
+	// 7. Video blocks with wp-video-{id} class — src may be on a child element.
+	if ( preg_match_all( '/class="[^"]*wp-video-(\d+)[^"]*".*?(?:src|data-src)="([^"]+)"/s', $content, $matches, PREG_SET_ORDER ) ) {
+		foreach ( $matches as $match ) {
+			$results[] = [
+				'attachment_id' => (int) $match[1],
+				'attachment_url' => clean_url( $match[2] ),
+				'modified_url'  => $match[2],
+			];
+		}
+	}
+
+	// Deduplicate by attachment_id (keep first occurrence).
+	$seen = [];
+	$unique_results = [];
+	foreach ( $results as $result ) {
+		$id = $result['attachment_id'];
+		if ( $id > 0 && ! isset( $seen[ $id ] ) ) {
+			$seen[ $id ] = true;
+			$unique_results[] = $result;
+		}
+	}
+
+	return $unique_results;
+}
+
+/**
+ * Extract unique attachment IDs from post content.
+ *
+ * Convenience wrapper around extract_attachments_from_content().
+ *
+ * @param string $content The post content to parse.
+ * @return int[] Array of unique attachment IDs.
+ */
+function extract_attachment_ids_from_content( string $content ) : array {
+	$attachments = extract_attachments_from_content( $content );
+	return array_values( array_unique( array_column( $attachments, 'attachment_id' ) ) );
+}
+
+/**
+ * Clean a URL by stripping query parameters and converting CDN/Tachyon URLs to canonical S3 paths.
+ *
+ * @param string $url The URL to clean.
+ * @return string The cleaned URL.
+ */
+function clean_url( string $url ) : string {
+	// Strip query parameters.
+	$url = strtok( $url, '?' );
+	if ( $url === false ) {
+		return '';
+	}
+
+	// Convert Tachyon URLs to canonical upload paths.
+	// Tachyon URLs typically follow the pattern: /tachyon/uploads/path/to/file.jpg
+	$url = preg_replace( '#/tachyon/(uploads/.+)$#', '/wp-content/$1', $url );
+
+	return $url;
+}
diff --git a/inc/private_media/namespace.php b/inc/private_media/namespace.php
new file mode 100644
index 0000000..4890c5c
--- /dev/null
+++ b/inc/private_media/namespace.php
@@ -0,0 +1,104 @@
+<?php
+/**
+ * Private Media — Bootstrap and Configuration.
+ *
+ * Main entry point for the Private Media feature. Handles feature detection,
+ * configuration, and hook orchestration.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media;
+
+use Altis;
+
+/**
+ * Check if the private media feature is active for the current site.
+ *
+ * Returns false for the global media library site and when the feature is
+ * disabled via configuration.
+ *
+ * @return bool True if private media is active.
+ */
+function is_private_media_active() : bool {
+	$config = Altis\get_config()['modules']['media'] ?? [];
+
+	// Check if explicitly disabled.
+	if ( isset( $config['private-media'] ) && $config['private-media'] === false ) {
+		return false;
+	}
+
+	// Disable on the global media library site.
+	// Only check when WP is fully loaded (get_site_meta is available).
+	if ( did_action( 'muplugins_loaded' ) ) {
+		if ( function_exists( '\\Altis\\Global_Content\\is_global_site' ) && \Altis\Global_Content\is_global_site() ) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Bootstrap the private media feature.
+ *
+ * Query compatibility always runs (even when inactive) to prevent data loss.
+ * All other hooks are gated behind is_private_media_active().
+ *
+ * @return void
+ */
+function bootstrap() {
+	// Query compat always runs — prevents data loss when feature is toggled off.
+	Query_Compat\bootstrap();
+
+	// Check config-level disable (safe to check early — no WP functions needed).
+	$config = Altis\get_config()['modules']['media'] ?? [];
+	if ( isset( $config['private-media'] ) && $config['private-media'] === false ) {
+		return;
+	}
+
+	// Defer remaining bootstrap until WP is loaded enough for is_global_site() etc.
+	// If muplugins_loaded has already fired (e.g. in test environments), call directly.
+	if ( did_action( 'muplugins_loaded' ) ) {
+		bootstrap_feature();
+	} else {
+		add_action( 'muplugins_loaded', __NAMESPACE__ . '\\bootstrap_feature' );
+	}
+}
+
+/**
+ * Bootstrap the private media feature after WordPress is loaded.
+ *
+ * Called on muplugins_loaded so that functions like get_site_meta() are available
+ * for the global site check.
+ *
+ * @return void
+ */
+function bootstrap_feature() {
+	if ( ! is_private_media_active() ) {
+		return;
+	}
+
+	// Core visibility logic (new attachment → private, S3 filters).
+	Visibility\bootstrap();
+
+	// Post lifecycle (publish/unpublish transitions).
+	Post_Lifecycle\bootstrap();
+
+	// Content sanitisation (strip AWS params).
+	Sanitisation\bootstrap();
+
+	// Signed URL previews.
+	Signed_Urls\bootstrap();
+
+	// Site icon handling.
+	Site_Icon\bootstrap();
+
+	// UI hooks (media library, row actions, bulk actions).
+	UI\bootstrap();
+
+	// CLI commands.
+	if ( defined( 'WP_CLI' ) && WP_CLI ) {
+		CLI\bootstrap();
+	}
+}
diff --git a/inc/private_media/post_lifecycle.php b/inc/private_media/post_lifecycle.php
new file mode 100644
index 0000000..c5b7237
--- /dev/null
+++ b/inc/private_media/post_lifecycle.php
@@ -0,0 +1,281 @@
+<?php
+/**
+ * Private Media — Post Lifecycle.
+ *
+ * Handles the publish/unpublish transitions that drive automatic attachment
+ * visibility changes. The heart of the Private Media feature.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Post_Lifecycle;
+
+use Altis\Media\Private_Media\Content_Parser;
+use Altis\Media\Private_Media\Visibility;
+use WP_Post;
+
+/**
+ * Bootstrap post lifecycle hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_action( 'transition_post_status', __NAMESPACE__ . '\\on_post_status_transition', 10, 3 );
+	add_action( 'save_post', __NAMESPACE__ . '\\on_save_post', 10, 2 );
+
+	// Add CSS classes to video and file block output for content parser detection.
+	add_filter( 'render_block_core/video', __NAMESPACE__ . '\\add_video_block_class', 10, 2 );
+	add_filter( 'render_block_core/file', __NAMESPACE__ . '\\add_file_block_class', 10, 2 );
+}
+
+/**
+ * Handle post status transitions.
+ *
+ * @param string  $new_status The new post status.
+ * @param string  $old_status The old post status.
+ * @param WP_Post $post       The post object.
+ * @return void
+ */
+function on_post_status_transition( string $new_status, string $old_status, WP_Post $post ) : void {
+	if ( ! is_allowed_post_type( $post->post_type ) ) {
+		return;
+	}
+
+	// Publishing: make attachments public.
+	if ( $new_status === 'publish' && $old_status !== 'publish' ) {
+		handle_publish( $post );
+		return;
+	}
+
+	// Unpublishing: make attachments private (if not used elsewhere).
+	if ( $old_status === 'publish' && $new_status !== 'publish' ) {
+		handle_unpublish( $post );
+		return;
+	}
+}
+
+/**
+ * Handle saving of a published post (detects removed attachments).
+ *
+ * @param int     $post_id The post ID.
+ * @param WP_Post $post    The post object.
+ * @return void
+ */
+function on_save_post( int $post_id, WP_Post $post ) : void {
+	if ( $post->post_status !== 'publish' ) {
+		return;
+	}
+
+	if ( ! is_allowed_post_type( $post->post_type ) ) {
+		return;
+	}
+
+	// Avoid running during the transition_post_status handler.
+	if ( doing_action( 'transition_post_status' ) ) {
+		return;
+	}
+
+	handle_resave( $post );
+}
+
+/**
+ * Handle a post being published.
+ *
+ * Gathers attachment IDs, adds post references, sets visibility, and stores
+ * the ID list in post meta for future diff detection.
+ *
+ * @param WP_Post $post The post being published.
+ * @return void
+ */
+function handle_publish( WP_Post $post ) : void {
+	$attachment_ids = get_post_attachment_ids( $post );
+
+	foreach ( $attachment_ids as $attachment_id ) {
+		Visibility\add_post_reference( $attachment_id, $post->ID );
+		Visibility\set_attachment_visibility( $attachment_id );
+	}
+
+	// Store current attachment IDs for future removed-attachment diffing.
+	update_post_meta( $post->ID, 'altis_private_media_post', $attachment_ids );
+}
+
+/**
+ * Handle a post being unpublished.
+ *
+ * Removes post references and re-evaluates visibility for each attachment.
+ *
+ * @param WP_Post $post The post being unpublished.
+ * @return void
+ */
+function handle_unpublish( WP_Post $post ) : void {
+	$attachment_ids = get_post_attachment_ids( $post );
+
+	// Also include previously stored IDs (in case content was changed before unpublish).
+	$stored_ids = get_post_meta( $post->ID, 'altis_private_media_post', true );
+	if ( is_array( $stored_ids ) ) {
+		$attachment_ids = array_unique( array_merge( $attachment_ids, $stored_ids ) );
+	}
+
+	foreach ( $attachment_ids as $attachment_id ) {
+		Visibility\remove_post_reference( $attachment_id, $post->ID );
+		Visibility\set_attachment_visibility( $attachment_id );
+	}
+
+	delete_post_meta( $post->ID, 'altis_private_media_post' );
+}
+
+/**
+ * Handle re-saving a published post.
+ *
+ * Diffs current attachment IDs against previously stored ones to detect
+ * removed attachments that may need to go private.
+ *
+ * @param WP_Post $post The post being re-saved.
+ * @return void
+ */
+function handle_resave( WP_Post $post ) : void {
+	$current_ids = get_post_attachment_ids( $post );
+	$stored_ids = get_post_meta( $post->ID, 'altis_private_media_post', true );
+
+	if ( ! is_array( $stored_ids ) ) {
+		$stored_ids = [];
+	}
+
+	// Newly added attachments.
+	$added = array_diff( $current_ids, $stored_ids );
+	foreach ( $added as $attachment_id ) {
+		Visibility\add_post_reference( $attachment_id, $post->ID );
+		Visibility\set_attachment_visibility( $attachment_id );
+	}
+
+	// Removed attachments — may need to go private.
+	$removed = array_diff( $stored_ids, $current_ids );
+	foreach ( $removed as $attachment_id ) {
+		Visibility\remove_post_reference( $attachment_id, $post->ID );
+		Visibility\set_attachment_visibility( $attachment_id );
+	}
+
+	// Update stored list.
+	update_post_meta( $post->ID, 'altis_private_media_post', $current_ids );
+}
+
+/**
+ * Get all attachment IDs associated with a post.
+ *
+ * Combines content parsing, featured image, and filterable additional sources.
+ *
+ * @param WP_Post $post The post.
+ * @return int[] Array of attachment IDs.
+ */
+function get_post_attachment_ids( WP_Post $post ) : array {
+	// Parse content for embedded attachments.
+	$ids = Content_Parser\extract_attachment_ids_from_content( $post->post_content );
+
+	// Include featured image.
+	$thumbnail_id = (int) get_post_thumbnail_id( $post->ID );
+	if ( $thumbnail_id > 0 ) {
+		$ids[] = $thumbnail_id;
+	}
+
+	// Check registered meta keys that store attachment IDs.
+	$meta_keys = apply_filters( 'private_media/post_meta_attachment_keys', [], $post->ID );
+	foreach ( $meta_keys as $meta_key ) {
+		$meta_value = get_post_meta( $post->ID, $meta_key, true );
+		if ( is_numeric( $meta_value ) && (int) $meta_value > 0 ) {
+			$ids[] = (int) $meta_value;
+		}
+	}
+
+	/**
+	 * Filter the attachment IDs associated with a post.
+	 *
+	 * @param int[]   $ids     Array of attachment IDs.
+	 * @param int     $post_id The post ID.
+	 * @param WP_Post $post    The post object.
+	 */
+	$ids = apply_filters( 'private_media/post_attachment_ids', $ids, $post->ID, $post );
+
+	// Ensure all IDs are valid attachment IDs.
+	$ids = array_filter( array_unique( array_map( 'intval', $ids ) ), function ( int $id ) : bool {
+		return $id > 0 && get_post_type( $id ) === 'attachment';
+	} );
+
+	return array_values( $ids );
+}
+
+/**
+ * Check if a post type is allowed for private media transitions.
+ *
+ * @param string $post_type The post type to check.
+ * @return bool True if the post type should trigger attachment transitions.
+ */
+function is_allowed_post_type( string $post_type ) : bool {
+	// Default: all post types with editor support, plus customize_changeset.
+	$allowed = get_post_types_by_support( 'editor' );
+	$allowed[] = 'customize_changeset';
+
+	/**
+	 * Filter which post types trigger attachment visibility transitions.
+	 *
+	 * @param string[] $allowed Array of allowed post type names.
+	 */
+	$allowed = apply_filters( 'private_media/allowed_post_types', $allowed );
+
+	return in_array( $post_type, $allowed, true );
+}
+
+/**
+ * Add wp-video-{id} class to video block output.
+ *
+ * This allows the content parser to identify video attachments in rendered content.
+ *
+ * @param string $block_content The block content.
+ * @param array  $block         The block data.
+ * @return string Modified block content.
+ */
+function add_video_block_class( string $block_content, array $block ) : string {
+	if ( empty( $block['attrs']['id'] ) ) {
+		return $block_content;
+	}
+
+	$id = (int) $block['attrs']['id'];
+	$class = 'wp-video-' . $id;
+
+	// Add class to the <figure> wrapper.
+	$block_content = preg_replace(
+		'/(<figure\b[^>]*class="[^"]*)(")/s',
+		'$1 ' . esc_attr( $class ) . '$2',
+		$block_content,
+		1
+	);
+
+	return $block_content;
+}
+
+/**
+ * Add wp-file-{id} class to file block output.
+ *
+ * This allows the content parser to identify file attachments in rendered content.
+ *
+ * @param string $block_content The block content.
+ * @param array  $block         The block data.
+ * @return string Modified block content.
+ */
+function add_file_block_class( string $block_content, array $block ) : string {
+	if ( empty( $block['attrs']['id'] ) ) {
+		return $block_content;
+	}
+
+	$id = (int) $block['attrs']['id'];
+	$class = 'wp-file-' . $id;
+
+	// Add class to the block wrapper element.
+	$block_content = preg_replace(
+		'/(<div\b[^>]*class="[^"]*wp-block-file[^"]*)(")/s',
+		'$1 ' . esc_attr( $class ) . '$2',
+		$block_content,
+		1
+	);
+
+	return $block_content;
+}
diff --git a/inc/private_media/query_compat.php b/inc/private_media/query_compat.php
new file mode 100644
index 0000000..5b95122
--- /dev/null
+++ b/inc/private_media/query_compat.php
@@ -0,0 +1,64 @@
+<?php
+/**
+ * Private Media — Attachment Query Compatibility.
+ *
+ * Ensures attachment queries include 'publish' and 'private' statuses alongside 'inherit'.
+ * Runs unconditionally (even when private media feature is inactive) to prevent data loss.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Query_Compat;
+
+/**
+ * Bootstrap query compatibility hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_action( 'pre_get_posts', __NAMESPACE__ . '\\filter_attachment_query' );
+}
+
+/**
+ * Ensure attachment queries include publish and private statuses.
+ *
+ * WordPress core media queries filter by post_status='inherit'. Since private media
+ * uses 'private' and 'publish' statuses, we need to expand the query to include them.
+ *
+ * @param \WP_Query $query The WP_Query instance.
+ * @return void
+ */
+function filter_attachment_query( \WP_Query $query ) {
+	// Only modify queries targeting the attachment post type.
+	$post_type = $query->get( 'post_type' );
+	if ( $post_type !== 'attachment' && ! ( is_array( $post_type ) && in_array( 'attachment', $post_type, true ) ) ) {
+		return;
+	}
+
+	$post_status = $query->get( 'post_status' );
+
+	// Handle string status.
+	if ( is_string( $post_status ) && ! empty( $post_status ) ) {
+		$post_status = array_map( 'trim', explode( ',', $post_status ) );
+	}
+
+	// Handle empty / default status — WP defaults to 'inherit' for attachment queries.
+	if ( empty( $post_status ) ) {
+		$post_status = [ 'inherit' ];
+	}
+
+	if ( ! is_array( $post_status ) ) {
+		return;
+	}
+
+	// If 'inherit' is in the statuses, also add 'publish' and 'private'.
+	if ( in_array( 'inherit', $post_status, true ) ) {
+		if ( ! in_array( 'publish', $post_status, true ) ) {
+			$post_status[] = 'publish';
+		}
+		if ( ! in_array( 'private', $post_status, true ) ) {
+			$post_status[] = 'private';
+		}
+		$query->set( 'post_status', $post_status );
+	}
+}
diff --git a/inc/private_media/sanitisation.php b/inc/private_media/sanitisation.php
new file mode 100644
index 0000000..bf52a9e
--- /dev/null
+++ b/inc/private_media/sanitisation.php
@@ -0,0 +1,161 @@
+<?php
+/**
+ * Private Media — Content Sanitisation.
+ *
+ * Strips AWS signing parameters from URLs in post content and widgets on save
+ * to prevent credentials from being persisted in the database.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Sanitisation;
+
+use Altis\Media\Private_Media\Content_Parser;
+use Altis\Media\Private_Media\Visibility;
+
+/**
+ * AWS parameters to strip from URLs.
+ */
+const AWS_PARAMS = [
+	'X-Amz-Content-Sha256',
+	'X-Amz-Security-Token',
+	'X-Amz-Algorithm',
+	'X-Amz-Credential',
+	'X-Amz-Date',
+	'X-Amz-SignedHeaders',
+	'X-Amz-Expires',
+	'X-Amz-Signature',
+	'X-Amz-S3-Host',
+	'presign',
+];
+
+/**
+ * Bootstrap sanitisation hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_filter( 'wp_insert_post_data', __NAMESPACE__ . '\\sanitise_post_content', 10, 1 );
+	add_filter( 'pre_update_option_widget_block', __NAMESPACE__ . '\\sanitise_widget_content', 10, 1 );
+}
+
+/**
+ * Strip AWS signing parameters from post content on save.
+ *
+ * @param array $data The post data array.
+ * @return array Modified post data.
+ */
+function sanitise_post_content( array $data ) : array {
+	if ( empty( $data['post_content'] ) ) {
+		return $data;
+	}
+
+	$data['post_content'] = strip_aws_params_from_content( $data['post_content'] );
+
+	return $data;
+}
+
+/**
+ * Strip AWS signing parameters from widget block content.
+ *
+ * Also forces all images found in widgets to public since widgets
+ * have no publish/draft lifecycle.
+ *
+ * @param mixed $value The widget option value.
+ * @return mixed Modified widget value.
+ */
+function sanitise_widget_content( $value ) {
+	if ( ! is_string( $value ) ) {
+		return $value;
+	}
+
+	$value = strip_aws_params_from_content( $value );
+
+	// Force images in widgets to public.
+	$attachment_ids = Content_Parser\extract_attachment_ids_from_content( $value );
+	foreach ( $attachment_ids as $attachment_id ) {
+		Visibility\set_override( $attachment_id, 'public' );
+	}
+
+	return $value;
+}
+
+/**
+ * Strip AWS signing parameters from all URLs in a content string.
+ *
+ * @param string $content The content to sanitise.
+ * @return string Sanitised content.
+ */
+function strip_aws_params_from_content( string $content ) : string {
+	if ( empty( $content ) ) {
+		return $content;
+	}
+
+	// Build regex pattern matching any of the AWS parameters.
+	$param_pattern = implode( '|', array_map( 'preg_quote', AWS_PARAMS ) );
+
+	// Match URLs containing AWS parameters and strip those params.
+	// This handles URLs in src="...", href="...", and JSON strings.
+	$content = preg_replace_callback(
+		'/((?:src|href|data-full-url|data-src)="[^"]*\?)([^"]*")/s',
+		function ( $matches ) use ( $param_pattern ) {
+			$prefix = $matches[1];
+			$rest = $matches[2];
+
+			// Strip the leading ? and trailing "
+			$query_and_quote = $rest;
+			$quote = substr( $query_and_quote, -1 );
+			$query = substr( $query_and_quote, 0, -1 );
+
+			$query = strip_aws_params_from_query( $query, $param_pattern );
+
+			if ( empty( $query ) ) {
+				// Remove the ? too.
+				return substr( $prefix, 0, -1 ) . $quote;
+			}
+
+			return $prefix . $query . $quote;
+		},
+		$content
+	);
+
+	// Also handle URLs in JSON block attributes (escaped quotes).
+	$content = preg_replace_callback(
+		'/((?:"src"|"imageUrl"|"href")\s*:\s*"[^"]*\?)([^"]*")/s',
+		function ( $matches ) use ( $param_pattern ) {
+			$prefix = $matches[1];
+			$rest = $matches[2];
+
+			$quote = substr( $rest, -1 );
+			$query = substr( $rest, 0, -1 );
+
+			$query = strip_aws_params_from_query( $query, $param_pattern );
+
+			if ( empty( $query ) ) {
+				return substr( $prefix, 0, -1 ) . $quote;
+			}
+
+			return $prefix . $query . $quote;
+		},
+		$content
+	);
+
+	return $content;
+}
+
+/**
+ * Strip AWS parameters from a query string.
+ *
+ * @param string $query         The query string (without leading ?).
+ * @param string $param_pattern Regex pattern for parameter names.
+ * @return string Filtered query string.
+ */
+function strip_aws_params_from_query( string $query, string $param_pattern ) : string {
+	// Split on & and filter out AWS params.
+	$parts = explode( '&', $query );
+	$parts = array_filter( $parts, function ( string $part ) use ( $param_pattern ) : bool {
+		return ! preg_match( '/^(' . $param_pattern . ')=/i', $part );
+	} );
+
+	return implode( '&', $parts );
+}
diff --git a/inc/private_media/signed_urls.php b/inc/private_media/signed_urls.php
new file mode 100644
index 0000000..b2b8120
--- /dev/null
+++ b/inc/private_media/signed_urls.php
@@ -0,0 +1,148 @@
+<?php
+/**
+ * Private Media — Signed URL Previews.
+ *
+ * Replaces private media URLs with signed S3 URLs in preview contexts
+ * and disables srcset generation for previews.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Signed_Urls;
+
+use Altis\Media\Private_Media\Content_Parser;
+use Altis\Media\Private_Media\Visibility;
+
+/**
+ * Bootstrap signed URL hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_filter( 'the_content', __NAMESPACE__ . '\\replace_private_urls_in_preview', 999 );
+
+	// Register REST filters for all post types with editor support.
+	add_action( 'rest_api_init', __NAMESPACE__ . '\\register_rest_filters' );
+
+	add_filter( 'wp_calculate_image_srcset', __NAMESPACE__ . '\\disable_srcset_in_preview', 10, 1 );
+}
+
+/**
+ * Replace private media URLs with signed S3 URLs in preview mode.
+ *
+ * Only runs on is_preview() context.
+ *
+ * @param string $content The post content.
+ * @return string Content with signed URLs.
+ */
+function replace_private_urls_in_preview( string $content ) : string {
+	if ( ! is_preview() ) {
+		return $content;
+	}
+
+	return replace_private_urls( $content );
+}
+
+/**
+ * Register REST API filters for signed URLs in draft/future posts.
+ *
+ * @return void
+ */
+function register_rest_filters() {
+	$post_types = get_post_types_by_support( 'editor' );
+
+	foreach ( $post_types as $post_type ) {
+		add_filter( "rest_prepare_{$post_type}", __NAMESPACE__ . '\\sign_rest_content', 10, 2 );
+	}
+}
+
+/**
+ * Add signed URLs to REST API response content for drafts/future posts.
+ *
+ * @param \WP_REST_Response $response The REST response.
+ * @param \WP_Post          $post     The post object.
+ * @return \WP_REST_Response
+ */
+function sign_rest_content( \WP_REST_Response $response, \WP_Post $post ) : \WP_REST_Response {
+	// Only sign URLs for non-published posts.
+	if ( $post->post_status === 'publish' ) {
+		return $response;
+	}
+
+	$data = $response->get_data();
+
+	if ( ! empty( $data['content']['raw'] ) ) {
+		$data['content']['raw'] = replace_private_urls( $data['content']['raw'] );
+		$response->set_data( $data );
+	}
+
+	return $response;
+}
+
+/**
+ * Replace private media URLs in content with signed S3 URLs.
+ *
+ * Images are routed through Tachyon after signing so that the presign query
+ * parameters are bundled correctly. Non-image files (PDFs, videos, etc.)
+ * use the signed URL directly.
+ *
+ * @param string $content The content to process.
+ * @return string Content with private URLs replaced by signed ones.
+ */
+function replace_private_urls( string $content ) : string {
+	if ( ! class_exists( '\\S3_Uploads\\Plugin' ) ) {
+		return $content;
+	}
+
+	$attachments = Content_Parser\extract_attachments_from_content( $content );
+
+	foreach ( $attachments as $attachment ) {
+		$attachment_id = $attachment['attachment_id'];
+
+		// Only sign URLs for private attachments.
+		if ( Visibility\check_attachment_is_public( $attachment_id ) ) {
+			continue;
+		}
+
+		// Sign the cleaned attachment URL (no query params, canonical path)
+		// so the S3 signature is computed against the correct key.
+		$attachment_url = $attachment['attachment_url'];
+		$signed_url = \S3_Uploads\Plugin::get_instance()->add_s3_signed_params_to_attachment_url(
+			$attachment_url,
+			$attachment_id
+		);
+
+		if ( $signed_url !== $attachment_url ) {
+			// Route images through Tachyon so it can handle resizing and
+			// forward the S3 signing params to the origin.
+			if ( function_exists( 'tachyon_url' ) && wp_attachment_is_image( $attachment_id ) ) {
+				$signed_url = tachyon_url( $signed_url );
+			}
+
+			$content = str_replace( $attachment['modified_url'], $signed_url, $content );
+		}
+	}
+
+	return $content;
+}
+
+/**
+ * Disable srcset generation in preview mode.
+ *
+ * Signed URLs are unique per size and cannot work with responsive image switching.
+ *
+ * @param array $sources Array of image source data.
+ * @return array Empty array in preview mode, original sources otherwise.
+ */
+function disable_srcset_in_preview( array $sources ) : array {
+	if ( is_preview() ) {
+		return [];
+	}
+
+	// Also disable in REST context for non-published posts.
+	if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
+		return [];
+	}
+
+	return $sources;
+}
diff --git a/inc/private_media/site_icon.php b/inc/private_media/site_icon.php
new file mode 100644
index 0000000..422a849
--- /dev/null
+++ b/inc/private_media/site_icon.php
@@ -0,0 +1,56 @@
+<?php
+/**
+ * Private Media — Site Icon Handling.
+ *
+ * Ensures the site icon attachment is always treated as public.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Site_Icon;
+
+use Altis\Media\Private_Media\Visibility;
+
+/**
+ * Bootstrap site icon hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_action( 'update_option_site_icon', __NAMESPACE__ . '\\on_site_icon_update', 10, 2 );
+}
+
+/**
+ * Handle site icon option updates.
+ *
+ * Marks the new icon attachment with site_icon metadata and clears it from the old icon.
+ *
+ * @param mixed $old_value The old site icon attachment ID.
+ * @param mixed $new_value The new site icon attachment ID.
+ * @return void
+ */
+function on_site_icon_update( $old_value, $new_value ) : void {
+	$old_id = (int) $old_value;
+	$new_id = (int) $new_value;
+
+	// Clear site_icon flag from old attachment.
+	if ( $old_id > 0 ) {
+		$metadata = wp_get_attachment_metadata( $old_id );
+		if ( is_array( $metadata ) ) {
+			unset( $metadata['site_icon'] );
+			wp_update_attachment_metadata( $old_id, $metadata );
+			Visibility\set_attachment_visibility( $old_id );
+		}
+	}
+
+	// Set site_icon flag on new attachment.
+	if ( $new_id > 0 ) {
+		$metadata = wp_get_attachment_metadata( $new_id );
+		if ( ! is_array( $metadata ) ) {
+			$metadata = [];
+		}
+		$metadata['site_icon'] = true;
+		wp_update_attachment_metadata( $new_id, $metadata );
+		Visibility\set_attachment_visibility( $new_id );
+	}
+}
diff --git a/inc/private_media/ui.php b/inc/private_media/ui.php
new file mode 100644
index 0000000..60a6073
--- /dev/null
+++ b/inc/private_media/ui.php
@@ -0,0 +1,557 @@
+<?php
+/**
+ * Private Media — UI.
+ *
+ * Media library UI: row actions, bulk action, modal sidebar controls,
+ * and lock icon overlay for private attachments.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\UI;
+
+use Altis\Media\Private_Media\Visibility;
+use Altis\Media\Private_Media\Post_Lifecycle;
+use WP_Post;
+
+/**
+ * Bootstrap UI hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	// Media list row actions.
+	add_filter( 'media_row_actions', __NAMESPACE__ . '\\add_media_row_actions', 10, 2 );
+
+	// Post/page row actions.
+	add_filter( 'post_row_actions', __NAMESPACE__ . '\\add_post_row_actions', 10, 2 );
+	add_filter( 'page_row_actions', __NAMESPACE__ . '\\add_post_row_actions', 10, 2 );
+
+	// Bulk action.
+	add_filter( 'bulk_actions-upload', __NAMESPACE__ . '\\add_bulk_actions' );
+	add_filter( 'handle_bulk_actions-upload', __NAMESPACE__ . '\\handle_bulk_actions', 10, 3 );
+
+	// Media modal sidebar: visibility dropdown.
+	add_filter( 'attachment_fields_to_edit', __NAMESPACE__ . '\\add_visibility_field', 10, 2 );
+	add_filter( 'attachment_fields_to_save', __NAMESPACE__ . '\\save_visibility_field', 10, 2 );
+
+	// AJAX handler for modal visibility changes.
+	add_action( 'wp_ajax_private_media_set_visibility', __NAMESPACE__ . '\\ajax_set_visibility' );
+
+	// Media list visibility column.
+	add_filter( 'manage_media_columns', __NAMESPACE__ . '\\add_visibility_column' );
+	add_action( 'manage_media_custom_column', __NAMESPACE__ . '\\render_visibility_column', 10, 2 );
+
+	// Enqueue assets.
+	add_action( 'admin_enqueue_scripts', __NAMESPACE__ . '\\enqueue_assets' );
+
+	// Admin action handlers.
+	add_action( 'admin_init', __NAMESPACE__ . '\\handle_row_actions' );
+
+	// Admin notices.
+	add_action( 'admin_notices', __NAMESPACE__ . '\\display_admin_notices' );
+
+	// Bulk action confirmation screen.
+	add_action( 'admin_action_private_media_bulk_visibility', __NAMESPACE__ . '\\bulk_visibility_confirmation' );
+}
+
+/**
+ * Add row actions to media list table.
+ *
+ * @param array   $actions Existing row actions.
+ * @param WP_Post $post    The attachment post object.
+ * @return array Modified actions.
+ */
+function add_media_row_actions( array $actions, WP_Post $post ) : array {
+	if ( $post->post_type !== 'attachment' ) {
+		return $actions;
+	}
+
+	if ( ! current_user_can( 'edit_post', $post->ID ) ) {
+		return $actions;
+	}
+
+	$override = Visibility\get_override( $post->ID );
+	$nonce = wp_create_nonce( 'private_media_action_' . $post->ID );
+
+	if ( $override !== 'public' ) {
+		$actions['private_media_public'] = sprintf(
+			'<a href="%s">%s</a>',
+			esc_url( admin_url( sprintf(
+				'upload.php?action=private_media_set_public&attachment_id=%d&_wpnonce=%s',
+				$post->ID,
+				$nonce
+			) ) ),
+			esc_html__( 'Make Public', 'altis' )
+		);
+	}
+
+	if ( $override !== 'private' ) {
+		$actions['private_media_private'] = sprintf(
+			'<a href="%s">%s</a>',
+			esc_url( admin_url( sprintf(
+				'upload.php?action=private_media_set_private&attachment_id=%d&_wpnonce=%s',
+				$post->ID,
+				$nonce
+			) ) ),
+			esc_html__( 'Make Private', 'altis' )
+		);
+	}
+
+	if ( $override !== 'auto' ) {
+		$actions['private_media_auto'] = sprintf(
+			'<a href="%s">%s</a>',
+			esc_url( admin_url( sprintf(
+				'upload.php?action=private_media_set_auto&attachment_id=%d&_wpnonce=%s',
+				$post->ID,
+				$nonce
+			) ) ),
+			esc_html__( 'Remove Override', 'altis' )
+		);
+	}
+
+	return $actions;
+}
+
+/**
+ * Add row actions to post/page list tables.
+ *
+ * @param array   $actions Existing row actions.
+ * @param WP_Post $post    The post object.
+ * @return array Modified actions.
+ */
+function add_post_row_actions( array $actions, WP_Post $post ) : array {
+	if ( ! Post_Lifecycle\is_allowed_post_type( $post->post_type ) ) {
+		return $actions;
+	}
+
+	if ( ! current_user_can( 'edit_post', $post->ID ) ) {
+		return $actions;
+	}
+
+	$nonce = wp_create_nonce( 'private_media_rescan_' . $post->ID );
+
+	if ( $post->post_status === 'publish' ) {
+		$actions['private_media_publish_images'] = sprintf(
+			'<a href="%s">%s</a>',
+			esc_url( admin_url( sprintf(
+				'admin.php?action=private_media_rescan&post_id=%d&visibility=publish&_wpnonce=%s',
+				$post->ID,
+				$nonce
+			) ) ),
+			esc_html__( 'Publish image(s)', 'altis' )
+		);
+	}
+
+	$actions['private_media_unpublish_images'] = sprintf(
+		'<a href="%s">%s</a>',
+		esc_url( admin_url( sprintf(
+			'admin.php?action=private_media_rescan&post_id=%d&visibility=unpublish&_wpnonce=%s',
+			$post->ID,
+			$nonce
+		) ) ),
+		esc_html__( 'Unpublish image(s)', 'altis' )
+	);
+
+	return $actions;
+}
+
+/**
+ * Handle row action requests.
+ *
+ * @return void
+ */
+function handle_row_actions() : void {
+	// Handle media visibility row actions.
+	$action = sanitize_text_field( $_GET['action'] ?? '' );
+	$attachment_id = (int) ( $_GET['attachment_id'] ?? 0 );
+	$post_id = (int) ( $_GET['post_id'] ?? 0 );
+
+	// Media visibility actions.
+	if ( in_array( $action, [ 'private_media_set_public', 'private_media_set_private', 'private_media_set_auto' ], true ) && $attachment_id > 0 ) {
+		check_admin_referer( 'private_media_action_' . $attachment_id );
+
+		if ( ! current_user_can( 'edit_post', $attachment_id ) ) {
+			wp_die( esc_html__( 'You do not have permission to modify this attachment.', 'altis' ) );
+		}
+
+		$visibility_map = [
+			'private_media_set_public'  => 'public',
+			'private_media_set_private' => 'private',
+			'private_media_set_auto'    => 'auto',
+		];
+
+		Visibility\set_override( $attachment_id, $visibility_map[ $action ] );
+
+		wp_safe_redirect( add_query_arg( 'private_media_updated', '1', admin_url( 'upload.php' ) ) );
+		exit;
+	}
+
+	// Post rescan action.
+	if ( $action === 'private_media_rescan' && $post_id > 0 ) {
+		check_admin_referer( 'private_media_rescan_' . $post_id );
+
+		if ( ! current_user_can( 'edit_post', $post_id ) ) {
+			wp_die( esc_html__( 'You do not have permission to modify this post.', 'altis' ) );
+		}
+
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			wp_die( esc_html__( 'Post not found.', 'altis' ) );
+		}
+
+		$visibility = sanitize_text_field( $_GET['visibility'] ?? 'publish' );
+		if ( $visibility === 'publish' ) {
+			Post_Lifecycle\handle_publish( $post );
+		} else {
+			Post_Lifecycle\handle_unpublish( $post );
+		}
+
+		// Mark as manually rescanned.
+		update_post_meta( $post_id, '_private_media_rescanned', true );
+
+		$redirect = admin_url( sprintf( 'edit.php?post_type=%s&private_media_rescanned=1', $post->post_type ) );
+		wp_safe_redirect( $redirect );
+		exit;
+	}
+}
+
+/**
+ * Register bulk action in media list table.
+ *
+ * @param array $actions Existing bulk actions.
+ * @return array Modified bulk actions.
+ */
+function add_bulk_actions( array $actions ) : array {
+	$actions['private_media_set_visibility'] = __( 'Set Visibility', 'altis' );
+	return $actions;
+}
+
+/**
+ * Handle bulk visibility action.
+ *
+ * @param string $redirect_to The redirect URL.
+ * @param string $doaction    The action being taken.
+ * @param array  $post_ids    Array of post IDs.
+ * @return string Modified redirect URL.
+ */
+function handle_bulk_actions( string $redirect_to, string $doaction, array $post_ids ) : string {
+	if ( $doaction !== 'private_media_set_visibility' ) {
+		return $redirect_to;
+	}
+
+	// Redirect to confirmation screen.
+	$ids = implode( ',', array_map( 'intval', $post_ids ) );
+	return admin_url( 'admin.php?action=private_media_bulk_visibility&attachment_ids=' . $ids . '&_wpnonce=' . wp_create_nonce( 'private_media_bulk' ) );
+}
+
+/**
+ * Display the bulk visibility confirmation screen.
+ *
+ * @return void
+ */
+function bulk_visibility_confirmation() : void {
+	check_admin_referer( 'private_media_bulk' );
+
+	$ids_string = sanitize_text_field( $_GET['attachment_ids'] ?? '' );
+	$ids = array_filter( array_map( 'intval', explode( ',', $ids_string ) ) );
+
+	if ( empty( $ids ) ) {
+		wp_die( esc_html__( 'No attachments selected.', 'altis' ) );
+	}
+
+	// Handle form submission.
+	if ( isset( $_POST['private_media_bulk_submit'] ) ) {
+		check_admin_referer( 'private_media_bulk_apply' );
+		$target = sanitize_text_field( $_POST['visibility'] ?? 'auto' );
+
+		$count = 0;
+		foreach ( $ids as $id ) {
+			if ( current_user_can( 'edit_post', $id ) ) {
+				Visibility\set_override( $id, $target );
+				$count++;
+			}
+		}
+
+		wp_safe_redirect( add_query_arg( 'private_media_bulk_updated', $count, admin_url( 'upload.php' ) ) );
+		exit;
+	}
+
+	// Display confirmation form.
+	require_once ABSPATH . 'wp-admin/admin-header.php';
+	?>
+	<div class="wrap">
+		<h1><?php esc_html_e( 'Set Media Visibility', 'altis' ); ?></h1>
+		<p><?php printf( esc_html__( 'You are about to change visibility for %d attachment(s).', 'altis' ), count( $ids ) ); ?></p>
+
+		<form method="post">
+			<?php wp_nonce_field( 'private_media_bulk_apply' ); ?>
+			<input type="hidden" name="attachment_ids" value="<?php echo esc_attr( $ids_string ); ?>" />
+
+			<table class="form-table">
+				<tr>
+					<th scope="row"><label for="visibility"><?php esc_html_e( 'Target Visibility', 'altis' ); ?></label></th>
+					<td>
+						<select name="visibility" id="visibility">
+							<option value="public"><?php esc_html_e( 'Force Public', 'altis' ); ?></option>
+							<option value="private"><?php esc_html_e( 'Force Private', 'altis' ); ?></option>
+							<option value="auto"><?php esc_html_e( 'Remove Override (Automatic)', 'altis' ); ?></option>
+						</select>
+					</td>
+				</tr>
+			</table>
+
+			<h2><?php esc_html_e( 'Selected Attachments', 'altis' ); ?></h2>
+			<ul>
+			<?php foreach ( $ids as $id ) : ?>
+				<?php $post = get_post( $id ); ?>
+				<?php if ( $post ) : ?>
+					<li><?php echo esc_html( $post->post_title ); ?> (ID: <?php echo esc_html( $id ); ?>)</li>
+				<?php endif; ?>
+			<?php endforeach; ?>
+			</ul>
+
+			<?php submit_button( __( 'Apply', 'altis' ), 'primary', 'private_media_bulk_submit' ); ?>
+		</form>
+	</div>
+	<?php
+	require_once ABSPATH . 'wp-admin/admin-footer.php';
+	exit;
+}
+
+/**
+ * Add visibility column to media list table.
+ *
+ * @param array $columns Existing columns.
+ * @return array Modified columns.
+ */
+function add_visibility_column( array $columns ) : array {
+	// Insert after the 'title' column.
+	$new_columns = [];
+	foreach ( $columns as $key => $label ) {
+		$new_columns[ $key ] = $label;
+		if ( $key === 'title' ) {
+			$new_columns['private_media_visibility'] = __( 'Visibility', 'altis' );
+		}
+	}
+
+	return $new_columns;
+}
+
+/**
+ * Render the visibility column content.
+ *
+ * @param string $column_name The column name.
+ * @param int    $post_id     The attachment ID.
+ * @return void
+ */
+function render_visibility_column( string $column_name, int $post_id ) : void {
+	if ( $column_name !== 'private_media_visibility' ) {
+		return;
+	}
+
+	$is_public = Visibility\check_attachment_is_public( $post_id );
+	$override = Visibility\get_override( $post_id );
+
+	if ( $override === 'public' ) {
+		echo '<span class="private-media-status private-media-status--public">' . esc_html__( 'Public (forced)', 'altis' ) . '</span>';
+	} elseif ( $override === 'private' ) {
+		echo '<span class="private-media-status private-media-status--private">' . esc_html__( 'Private (forced)', 'altis' ) . '</span>';
+	} elseif ( $is_public ) {
+		echo '<span class="private-media-status private-media-status--public">' . esc_html__( 'Public', 'altis' ) . '</span>';
+	} else {
+		echo '<span class="private-media-status private-media-status--private">' . esc_html__( 'Private', 'altis' ) . '</span>';
+	}
+}
+
+/**
+ * Add visibility field to media modal sidebar.
+ *
+ * @param array   $form_fields Existing form fields.
+ * @param WP_Post $post        The attachment post.
+ * @return array Modified form fields.
+ */
+function add_visibility_field( array $form_fields, WP_Post $post ) : array {
+	if ( $post->post_type !== 'attachment' ) {
+		return $form_fields;
+	}
+
+	$override = Visibility\get_override( $post->ID );
+	$is_public = Visibility\check_attachment_is_public( $post->ID );
+	$used_in = Visibility\get_used_in_posts( $post->ID );
+
+	// Status display.
+	$status_label = $is_public ? __( 'Public', 'altis' ) : __( 'Private', 'altis' );
+	if ( $override === 'public' ) {
+		$status_label = __( 'Forced Public', 'altis' );
+	} elseif ( $override === 'private' ) {
+		$status_label = __( 'Forced Private', 'altis' );
+	}
+
+	$form_fields['private_media_status'] = [
+		'label' => __( 'Attachment Status', 'altis' ),
+		'input' => 'html',
+		'html'  => '<strong>' . esc_html( $status_label ) . '</strong>',
+	];
+
+	// Visibility override dropdown.
+	$html = sprintf(
+		'<select name="attachments[%d][private_media_override]" class="private-media-override" data-attachment-id="%d">',
+		$post->ID,
+		$post->ID
+	);
+	$html .= sprintf( '<option value="auto" %s>%s</option>', selected( $override, 'auto', false ), esc_html__( 'Automatic', 'altis' ) );
+	$html .= sprintf( '<option value="public" %s>%s</option>', selected( $override, 'public', false ), esc_html__( 'Force Public', 'altis' ) );
+	$html .= sprintf( '<option value="private" %s>%s</option>', selected( $override, 'private', false ), esc_html__( 'Force Private', 'altis' ) );
+	$html .= '</select>';
+
+	$form_fields['private_media_override'] = [
+		'label' => __( 'Visibility Override', 'altis' ),
+		'input' => 'html',
+		'html'  => $html,
+	];
+
+	// Used In section.
+	if ( ! empty( $used_in ) ) {
+		$links = [];
+		foreach ( $used_in as $pid ) {
+			$title = get_the_title( $pid );
+			$edit_link = get_edit_post_link( $pid );
+			if ( $edit_link ) {
+				$links[] = sprintf( '<a href="%s">%s</a>', esc_url( $edit_link ), esc_html( $title ?: "#{$pid}" ) );
+			} else {
+				$links[] = esc_html( $title ?: "#{$pid}" );
+			}
+		}
+
+		$form_fields['private_media_used_in'] = [
+			'label' => __( 'Used In', 'altis' ),
+			'input' => 'html',
+			'html'  => implode( ', ', $links ),
+		];
+	}
+
+	// Legacy label.
+	$metadata = wp_get_attachment_metadata( $post->ID );
+	if ( is_array( $metadata ) && ! empty( $metadata['legacy_attachment'] ) ) {
+		$form_fields['private_media_legacy'] = [
+			'label' => __( 'Legacy', 'altis' ),
+			'input' => 'html',
+			'html'  => '<em>' . esc_html__( 'Pre-migration attachment', 'altis' ) . '</em>',
+		];
+	}
+
+	return $form_fields;
+}
+
+/**
+ * Save visibility field from media modal.
+ *
+ * @param array $post       The post data.
+ * @param array $attachment The attachment fields.
+ * @return array The post data.
+ */
+function save_visibility_field( array $post, array $attachment ) : array {
+	if ( ! empty( $attachment['private_media_override'] ) ) {
+		$override = sanitize_text_field( $attachment['private_media_override'] );
+		Visibility\set_override( (int) $post['ID'], $override );
+	}
+
+	return $post;
+}
+
+/**
+ * AJAX handler for setting visibility from the media modal.
+ *
+ * @return void
+ */
+function ajax_set_visibility() : void {
+	check_ajax_referer( 'private_media_ajax', 'nonce' );
+
+	$attachment_id = (int) ( $_POST['attachment_id'] ?? 0 );
+	$override = sanitize_text_field( $_POST['override'] ?? '' );
+
+	if ( $attachment_id <= 0 || ! in_array( $override, [ 'auto', 'public', 'private' ], true ) ) {
+		wp_send_json_error( [ 'message' => __( 'Invalid parameters.', 'altis' ) ] );
+	}
+
+	if ( ! current_user_can( 'edit_post', $attachment_id ) ) {
+		wp_send_json_error( [ 'message' => __( 'Permission denied.', 'altis' ) ] );
+	}
+
+	Visibility\set_override( $attachment_id, $override );
+
+	$is_public = Visibility\check_attachment_is_public( $attachment_id );
+	wp_send_json_success( [
+		'status'   => $is_public ? 'public' : 'private',
+		'override' => $override,
+	] );
+}
+
+/**
+ * Enqueue admin assets for private media UI.
+ *
+ * @param string $hook_suffix The current admin page hook.
+ * @return void
+ */
+function enqueue_assets( string $hook_suffix ) : void {
+	// Only enqueue on relevant pages.
+	if ( ! in_array( $hook_suffix, [ 'upload.php', 'post.php', 'post-new.php', 'media.php' ], true ) ) {
+		return;
+	}
+
+	$base_url = plugin_dir_url( dirname( __DIR__ ) );
+
+	wp_enqueue_script(
+		'private-media',
+		$base_url . 'assets/private-media.js',
+		[ 'jquery', 'media-views' ],
+		'1.0.0',
+		true
+	);
+
+	wp_localize_script( 'private-media', 'privateMedia', [
+		'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+		'nonce'   => wp_create_nonce( 'private_media_ajax' ),
+	] );
+
+	wp_enqueue_style(
+		'private-media',
+		$base_url . 'assets/private-media.css',
+		[],
+		'1.0.0'
+	);
+}
+
+/**
+ * Display admin notices for private media actions.
+ *
+ * @return void
+ */
+function display_admin_notices() : void {
+	if ( ! empty( $_GET['private_media_updated'] ) ) {
+		printf(
+			'<div class="notice notice-success is-dismissible"><p>%s</p></div>',
+			esc_html__( 'Attachment visibility updated.', 'altis' )
+		);
+	}
+
+	if ( ! empty( $_GET['private_media_bulk_updated'] ) ) {
+		$count = (int) $_GET['private_media_bulk_updated'];
+		printf(
+			'<div class="notice notice-success is-dismissible"><p>%s</p></div>',
+			sprintf(
+				/* translators: %d: number of attachments updated */
+				esc_html__( '%d attachment(s) updated.', 'altis' ),
+				$count
+			)
+		);
+	}
+
+	if ( ! empty( $_GET['private_media_rescanned'] ) ) {
+		printf(
+			'<div class="notice notice-success is-dismissible"><p>%s</p></div>',
+			esc_html__( 'Post images have been rescanned.', 'altis' )
+		);
+	}
+}
diff --git a/inc/private_media/visibility.php b/inc/private_media/visibility.php
new file mode 100644
index 0000000..c598281
--- /dev/null
+++ b/inc/private_media/visibility.php
@@ -0,0 +1,382 @@
+<?php
+/**
+ * Private Media — Visibility Logic.
+ *
+ * Core business logic for determining and setting attachment visibility.
+ * Implements the priority check from spec Section 3 and manages ACL updates.
+ *
+ * @package altis/media
+ */
+
+namespace Altis\Media\Private_Media\Visibility;
+
+/**
+ * Bootstrap visibility hooks.
+ *
+ * @return void
+ */
+function bootstrap() {
+	add_action( 'add_attachment', __NAMESPACE__ . '\\set_new_attachment_private' );
+	add_filter( 's3_uploads_is_attachment_private', __NAMESPACE__ . '\\filter_is_attachment_private', 10, 2 );
+	add_filter( 's3_uploads_private_attachment_url_expiry', __NAMESPACE__ . '\\filter_private_url_expiry', 10, 2 );
+	add_filter( 'map_meta_cap', __NAMESPACE__ . '\\grant_private_attachment_read', 10, 4 );
+}
+
+/**
+ * Check if an attachment should be public.
+ *
+ * Evaluated in priority order; first match wins (spec Section 3):
+ * 1. Force-private override → private
+ * 2. Force-public override → public
+ * 3. Used in a published post → public
+ * 4. Legacy attachment → public
+ * 5. Site icon → public
+ * 6. Default → private
+ *
+ * @param int $attachment_id The attachment ID.
+ * @return bool True if the attachment should be public.
+ */
+function check_attachment_is_public( int $attachment_id ) : bool {
+	$override = get_override( $attachment_id );
+
+	// 1. Force-private override — takes absolute precedence.
+	if ( $override === 'private' ) {
+		return false;
+	}
+
+	// 2. Force-public override.
+	if ( $override === 'public' ) {
+		return true;
+	}
+
+	// 3. Used in a published post.
+	$used_in = get_used_in_posts( $attachment_id );
+	if ( ! empty( $used_in ) ) {
+		return true;
+	}
+
+	// 4. Legacy attachment (pre-migration).
+	$metadata = wp_get_attachment_metadata( $attachment_id );
+	if ( is_array( $metadata ) && ! empty( $metadata['legacy_attachment'] ) ) {
+		return true;
+	}
+
+	// 5. Site icon — check metadata flag.
+	if ( is_array( $metadata ) && ! empty( $metadata['site_icon'] ) ) {
+		return true;
+	}
+
+	// 6. Fallback site icon check via option.
+	if ( (int) get_option( 'site_icon' ) === $attachment_id ) {
+		return true;
+	}
+
+	// 7. Default — private.
+	return false;
+}
+
+/**
+ * Set the visibility of an attachment based on the public check logic.
+ *
+ * Updates both post_status and S3 ACL.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @return void
+ */
+function set_attachment_visibility( int $attachment_id ) : void {
+	// Invalidate the per-request cache so the fresh check below is accurate.
+	is_attachment_private_cached( $attachment_id, true );
+
+	$is_public = check_attachment_is_public( $attachment_id );
+	$new_status = $is_public ? 'publish' : 'private';
+	$new_acl = $is_public ? 'public-read' : 'private';
+
+	$current_status = get_post_status( $attachment_id );
+
+	if ( $current_status !== $new_status ) {
+		wp_update_post( [
+			'ID'          => $attachment_id,
+			'post_status' => $new_status,
+		] );
+	}
+
+	update_s3_acl( $attachment_id, $new_acl );
+	purge_cdn_cache( $attachment_id );
+}
+
+/**
+ * Update the S3 ACL for an attachment.
+ *
+ * Filterable via 'private_media/update_s3_acl' for testing — if the filter
+ * returns non-null, the real S3 call is skipped.
+ *
+ * @param int    $attachment_id The attachment ID.
+ * @param string $acl           The ACL to set ('public-read' or 'private').
+ * @return void
+ */
+function update_s3_acl( int $attachment_id, string $acl ) : void {
+	/**
+	 * Filter to intercept S3 ACL updates (test seam).
+	 *
+	 * Return a non-null value to short-circuit the real S3 call.
+	 *
+	 * @param null|mixed $result        Return non-null to short-circuit.
+	 * @param int        $attachment_id The attachment ID.
+	 * @param string     $acl           The ACL being set.
+	 */
+	$result = apply_filters( 'private_media/update_s3_acl', null, $attachment_id, $acl );
+	if ( $result !== null ) {
+		return;
+	}
+
+	if ( ! class_exists( '\\S3_Uploads\\Plugin' ) ) {
+		return;
+	}
+
+	\S3_Uploads\Plugin::get_instance()->set_attachment_files_acl( $attachment_id, $acl );
+}
+
+/**
+ * Purge CDN cache for an attachment.
+ *
+ * Filterable via 'private_media/purge_cdn_cache' for testing.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @return void
+ */
+function purge_cdn_cache( int $attachment_id ) : void {
+	/**
+	 * Filter to intercept CDN cache purge (test seam).
+	 *
+	 * Return a non-null value to short-circuit.
+	 *
+	 * @param null|mixed $result        Return non-null to short-circuit.
+	 * @param int        $attachment_id The attachment ID.
+	 */
+	$result = apply_filters( 'private_media/purge_cdn_cache', null, $attachment_id );
+	if ( $result !== null ) {
+		return;
+	}
+
+	/**
+	 * Action fired when CDN cache should be purged for an attachment.
+	 *
+	 * @param int $attachment_id The attachment ID.
+	 */
+	do_action( 'private_media/do_purge_cdn_cache', $attachment_id );
+}
+
+/**
+ * Set newly uploaded attachments to private status.
+ *
+ * Hooked to 'add_attachment'.
+ *
+ * @param int $attachment_id The new attachment ID.
+ * @return void
+ */
+function set_new_attachment_private( int $attachment_id ) : void {
+	wp_update_post( [
+		'ID'          => $attachment_id,
+		'post_status' => 'private',
+	] );
+
+	update_s3_acl( $attachment_id, 'private' );
+}
+
+/**
+ * Get the manual override visibility for an attachment.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @return string 'auto', 'public', or 'private'.
+ */
+function get_override( int $attachment_id ) : string {
+	$metadata = wp_get_attachment_metadata( $attachment_id );
+	if ( ! is_array( $metadata ) || empty( $metadata['altis_override_visibility'] ) ) {
+		return 'auto';
+	}
+
+	$override = $metadata['altis_override_visibility'];
+	if ( in_array( $override, [ 'public', 'private' ], true ) ) {
+		return $override;
+	}
+
+	return 'auto';
+}
+
+/**
+ * Set the manual override visibility for an attachment.
+ *
+ * @param int    $attachment_id The attachment ID.
+ * @param string $override      'auto', 'public', or 'private'.
+ * @return void
+ */
+function set_override( int $attachment_id, string $override ) : void {
+	if ( ! in_array( $override, [ 'auto', 'public', 'private' ], true ) ) {
+		return;
+	}
+
+	$metadata = wp_get_attachment_metadata( $attachment_id );
+	if ( ! is_array( $metadata ) ) {
+		$metadata = [];
+	}
+
+	if ( $override === 'auto' ) {
+		unset( $metadata['altis_override_visibility'] );
+	} else {
+		$metadata['altis_override_visibility'] = $override;
+	}
+
+	wp_update_attachment_metadata( $attachment_id, $metadata );
+	set_attachment_visibility( $attachment_id );
+}
+
+/**
+ * Add a post reference to an attachment's metadata.
+ *
+ * Records that the given post uses this attachment.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @param int $post_id       The post ID that references this attachment.
+ * @return void
+ */
+function add_post_reference( int $attachment_id, int $post_id ) : void {
+	$used_in = get_used_in_posts( $attachment_id );
+
+	if ( ! in_array( $post_id, $used_in, true ) ) {
+		$used_in[] = $post_id;
+		set_used_in_posts( $attachment_id, $used_in );
+	}
+}
+
+/**
+ * Remove a post reference from an attachment's metadata.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @param int $post_id       The post ID to remove.
+ * @return void
+ */
+function remove_post_reference( int $attachment_id, int $post_id ) : void {
+	$used_in = get_used_in_posts( $attachment_id );
+	$used_in = array_values( array_diff( $used_in, [ $post_id ] ) );
+	set_used_in_posts( $attachment_id, $used_in );
+}
+
+/**
+ * Get the list of published post IDs that reference this attachment.
+ *
+ * @param int $attachment_id The attachment ID.
+ * @return int[] Array of post IDs.
+ */
+function get_used_in_posts( int $attachment_id ) : array {
+	$metadata = wp_get_attachment_metadata( $attachment_id );
+	if ( ! is_array( $metadata ) || empty( $metadata['altis_used_in_published_post'] ) ) {
+		return [];
+	}
+
+	return array_map( 'intval', (array) $metadata['altis_used_in_published_post'] );
+}
+
+/**
+ * Set the list of published post IDs that reference this attachment.
+ *
+ * @param int   $attachment_id The attachment ID.
+ * @param int[] $post_ids      Array of post IDs.
+ * @return void
+ */
+function set_used_in_posts( int $attachment_id, array $post_ids ) : void {
+	$metadata = wp_get_attachment_metadata( $attachment_id );
+	if ( ! is_array( $metadata ) ) {
+		$metadata = [];
+	}
+
+	if ( empty( $post_ids ) ) {
+		unset( $metadata['altis_used_in_published_post'] );
+	} else {
+		$metadata['altis_used_in_published_post'] = array_values( array_unique( array_map( 'intval', $post_ids ) ) );
+	}
+
+	wp_update_attachment_metadata( $attachment_id, $metadata );
+}
+
+/**
+ * Grant read access to private attachments for users who can upload files.
+ *
+ * WordPress maps 'read_post' for private posts to 'read_private_posts', which
+ * authors and contributors lack. This filter downgrades the capability requirement
+ * for private attachments so that any user with 'upload_files' can read them.
+ * Without this, wp_get_attachment_image(), wp_get_attachment_metadata(), and
+ * set_post_thumbnail() all fail for non-admin users.
+ *
+ * @param string[] $caps    Required capabilities.
+ * @param string   $cap     The capability being checked.
+ * @param int      $user_id The user ID.
+ * @param array    $args    Additional arguments (first element is the post ID).
+ * @return string[] Modified capabilities.
+ */
+function grant_private_attachment_read( array $caps, string $cap, int $user_id, array $args ) : array {
+	if ( $cap !== 'read_post' || empty( $args[0] ) ) {
+		return $caps;
+	}
+
+	$post = get_post( $args[0] );
+
+	// Only apply to private attachments — never modify caps for posts, pages, etc.
+	if ( $post && $post->post_type === 'attachment' && $post->post_status === 'private' ) {
+		// Replace 'read_private_posts' with 'upload_files' — any user who can
+		// upload media should be able to read private attachments.
+		return array_map( function ( $required_cap ) {
+			return $required_cap === 'read_private_posts' ? 'upload_files' : $required_cap;
+		}, $caps );
+	}
+
+	return $caps;
+}
+
+/**
+ * Per-request cache for attachment privacy checks.
+ *
+ * Avoids repeated DB lookups when S3 Uploads calls the filter for every
+ * URL of every image size (e.g. 40 attachments × 5 sizes = 200 calls
+ * per media library page load). Accepts an optional second parameter to
+ * clear a specific entry when visibility changes within the same request.
+ *
+ * @param int       $attachment_id The attachment ID.
+ * @param bool|null $invalidate    Pass true to clear the cached entry.
+ * @return bool|null True if private, false if public, null on invalidation.
+ */
+function is_attachment_private_cached( int $attachment_id, ?bool $invalidate = null ) : ?bool {
+	static $cache = [];
+
+	if ( $invalidate ) {
+		unset( $cache[ $attachment_id ] );
+		return null;
+	}
+
+	if ( ! isset( $cache[ $attachment_id ] ) ) {
+		$cache[ $attachment_id ] = ! check_attachment_is_public( $attachment_id );
+	}
+
+	return $cache[ $attachment_id ];
+}
+
+/**
+ * Filter callback for S3 Uploads private attachment check.
+ *
+ * @param bool $is_private Whether the attachment is private.
+ * @param int  $attachment_id The attachment ID.
+ * @return bool
+ */
+function filter_is_attachment_private( bool $is_private, int $attachment_id ) : bool {
+	return is_attachment_private_cached( $attachment_id ) ? true : $is_private;
+}
+
+/**
+ * Filter callback for signed URL expiry.
+ *
+ * @param string $expiry      The expiry string.
+ * @param int    $attachment_id The attachment ID.
+ * @return string
+ */
+function filter_private_url_expiry( string $expiry, int $attachment_id ) : string {
+	return '+15 minutes';
+}
diff --git a/load.php b/load.php
index 2ab186c..de22a3e 100644
--- a/load.php
+++ b/load.php
@@ -25,6 +25,7 @@
 		],
 		'global-media-library' => false,
 		'local-media-library' => true,
+		'private-media' => true,
 	];
 	$options = [
 		'defaults' => $default_settings,
diff --git a/tests/acceptance.suite.yml b/tests/acceptance.suite.yml
new file mode 100644
index 0000000..47b3c36
--- /dev/null
+++ b/tests/acceptance.suite.yml
@@ -0,0 +1,14 @@
+# Codeception Test Suite Configuration
+#
+# Suite for acceptance tests.
+# Perform tests in browser using the WPWebDriver or WPBrowser.
+# Use WPDb to set up your initial database fixture.
+# If you need both WPWebDriver and WPBrowser tests - create a separate suite.
+
+actor: AcceptanceTester
+modules:
+    enabled:
+        - WPDb
+        - WPWebDriver
+        - Asserts
+        - \Helper\Acceptance
diff --git a/tests/acceptance/PrivateMediaCest.php b/tests/acceptance/PrivateMediaCest.php
new file mode 100644
index 0000000..19f643e
--- /dev/null
+++ b/tests/acceptance/PrivateMediaCest.php
@@ -0,0 +1,151 @@
+<?php
+/**
+ * Acceptance tests for Private Media UI.
+ *
+ * Tests the media library interface for private/public visibility management.
+ *
+ * phpcs:disable WordPress.Files, WordPress.NamingConventions, PSR1.Classes.ClassDeclaration.MissingNamespace, HM.Functions.NamespacedFunctions
+ *
+ * @package altis/media
+ */
+
+/**
+ * Test Private Media UI features.
+ */
+class PrivateMediaCest {
+
+	/**
+	 * Test that a newly uploaded image appears as private in the media library.
+	 *
+	 * @param AcceptanceTester $I Tester.
+	 *
+	 * @return void
+	 */
+	public function newUploadIsPrivate( AcceptanceTester $I ) {
+		$I->wantToTest( 'Newly uploaded media is private by default.' );
+
+		$I->loginAsAdmin();
+
+		// Upload a file via the Add New Media page.
+		$I->amOnAdminPage( 'media-new.php' );
+		$I->see( 'Upload New Media' );
+		$I->attachFile( 'input[type="file"]', 'wp-logo.png' );
+		$I->wait( 3 );
+		$I->waitForElement( '.media-item', 30 );
+
+		// Go to the media library list view.
+		$I->amOnAdminPage( 'upload.php?mode=list' );
+		$I->waitForElement( '.wp-list-table', 10 );
+
+		// The most recent upload should show "Private" in the visibility column.
+		$I->see( 'Private', '.wp-list-table tbody tr:first-child .private-media-status' );
+
+		// Row actions should include "Make Public".
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->seeLink( 'Make Public' );
+	}
+
+	/**
+	 * Test the "Make Public" row action in the media library.
+	 *
+	 * @param AcceptanceTester $I Tester.
+	 *
+	 * @return void
+	 */
+	public function makePublicRowAction( AcceptanceTester $I ) {
+		$I->wantToTest( 'Make Public row action sets attachment to public.' );
+
+		$I->loginAsAdmin();
+
+		// Upload a file.
+		$I->amOnAdminPage( 'media-new.php' );
+		$I->attachFile( 'input[type="file"]', 'wp-logo.png' );
+		$I->wait( 3 );
+		$I->waitForElement( '.media-item', 30 );
+
+		// Go to the media library list view.
+		$I->amOnAdminPage( 'upload.php?mode=list' );
+		$I->waitForElement( '.wp-list-table', 10 );
+
+		// Hover over the first row to reveal actions and click Make Public.
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->seeLink( 'Make Public' );
+		$I->click( 'Make Public' );
+
+		// Should redirect back with success notice.
+		$I->waitForText( 'Attachment visibility updated.', 10 );
+
+		// The visibility column should now show "Public (forced)".
+		$I->see( 'Public (forced)', '.private-media-status' );
+	}
+
+	/**
+	 * Test the "Make Private" row action in the media library.
+	 *
+	 * @param AcceptanceTester $I Tester.
+	 *
+	 * @return void
+	 */
+	public function makePrivateRowAction( AcceptanceTester $I ) {
+		$I->wantToTest( 'Make Private row action sets attachment to private.' );
+
+		$I->loginAsAdmin();
+
+		// Upload a file and make it public first.
+		$I->amOnAdminPage( 'media-new.php' );
+		$I->attachFile( 'input[type="file"]', 'wp-logo.png' );
+		$I->wait( 3 );
+		$I->waitForElement( '.media-item', 30 );
+
+		$I->amOnAdminPage( 'upload.php?mode=list' );
+		$I->waitForElement( '.wp-list-table', 10 );
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->click( 'Make Public' );
+		$I->waitForText( 'Attachment visibility updated.', 10 );
+
+		// Now click Make Private.
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->seeLink( 'Make Private' );
+		$I->click( 'Make Private' );
+
+		// Should redirect back with success notice.
+		$I->waitForText( 'Attachment visibility updated.', 10 );
+
+		// The visibility column should now show "Private (forced)".
+		$I->see( 'Private (forced)', '.private-media-status' );
+	}
+
+	/**
+	 * Test the Remove Override row action in the media library.
+	 *
+	 * @param AcceptanceTester $I Tester.
+	 *
+	 * @return void
+	 */
+	public function removeOverrideRowAction( AcceptanceTester $I ) {
+		$I->wantToTest( 'Remove Override row action resets to automatic visibility.' );
+
+		$I->loginAsAdmin();
+
+		// Upload and force public.
+		$I->amOnAdminPage( 'media-new.php' );
+		$I->attachFile( 'input[type="file"]', 'wp-logo.png' );
+		$I->wait( 3 );
+		$I->waitForElement( '.media-item', 30 );
+
+		$I->amOnAdminPage( 'upload.php?mode=list' );
+		$I->waitForElement( '.wp-list-table', 10 );
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->click( 'Make Public' );
+		$I->waitForText( 'Attachment visibility updated.', 10 );
+
+		// Now remove override.
+		$I->moveMouseOver( '.wp-list-table tbody tr:first-child' );
+		$I->seeLink( 'Remove Override' );
+		$I->click( 'Remove Override' );
+		$I->waitForText( 'Attachment visibility updated.', 10 );
+
+		// Should revert to automatic (Private, since no references).
+		$I->see( 'Private', '.wp-list-table tbody tr:first-child .private-media-status' );
+	}
+}
diff --git a/tests/integration.suite.yml b/tests/integration.suite.yml
new file mode 100644
index 0000000..eda655a
--- /dev/null
+++ b/tests/integration.suite.yml
@@ -0,0 +1,9 @@
+# Codeception Test Suite Configuration
+#
+# Suite for integration tests that require WordPress functions and classes.
+
+actor: IntegrationTester
+modules:
+    enabled:
+        - WPLoader
+        - \Helper\Integration
diff --git a/tests/integration/PrivateMedia/ContentParserTest.php b/tests/integration/PrivateMedia/ContentParserTest.php
new file mode 100644
index 0000000..888cf91
--- /dev/null
+++ b/tests/integration/PrivateMedia/ContentParserTest.php
@@ -0,0 +1,137 @@
+<?php
+/**
+ * Test content parsing (spec Section 4).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+use Altis\Media\Private_Media\Content_Parser;
+
+class ContentParserTest extends \Codeception\TestCase\WPTestCase {
+
+	protected $tester;
+
+	public function testEmptyContentReturnsEmpty() {
+		$this->assertEmpty( Content_Parser\extract_attachments_from_content( '' ) );
+	}
+
+	public function testImageWithWpImageClass() {
+		$content = '<img class="wp-image-42 size-large" src="https://example.com/uploads/2024/01/photo.jpg" />';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 1, $results );
+		$this->assertEquals( 42, $results[0]['attachment_id'] );
+		$this->assertStringContainsString( 'photo.jpg', $results[0]['attachment_url'] );
+	}
+
+	public function testImageWithSrcBeforeClass() {
+		$content = '<img src="https://example.com/uploads/photo.jpg" class="wp-image-55 size-full" />';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 1, $results );
+		$this->assertEquals( 55, $results[0]['attachment_id'] );
+	}
+
+	public function testImageWithDataFullUrl() {
+		$content = '<img class="wp-image-10" src="https://example.com/small.jpg" data-full-url="https://example.com/uploads/full.jpg" />';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		// Should find the image (may have multiple matches but deduplicated by ID).
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertContains( 10, $ids );
+	}
+
+	public function testGutenbergImageUrlImageId() {
+		$content = '<!-- wp:cover {"imageUrl":"https:\/\/example.com\/uploads\/hero.jpg","imageId":77} -->';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 1, $results );
+		$this->assertEquals( 77, $results[0]['attachment_id'] );
+	}
+
+	public function testGutenbergIdSrc() {
+		$content = '<!-- wp:video {"id":33,"src":"https:\/\/example.com\/uploads\/video.mp4"} -->';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 1, $results );
+		$this->assertEquals( 33, $results[0]['attachment_id'] );
+	}
+
+	public function testVideoBlockWithCommentAndSrc() {
+		$content = '<!-- wp:video {"id":88} --><figure class="wp-block-video"><video src="https://example.com/uploads/clip.mp4"></video></figure><!-- /wp:video -->';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertContains( 88, $ids );
+	}
+
+	public function testFileBlockWithWpFileClass() {
+		$content = '<div class="wp-block-file wp-file-22"><a href="https://example.com/uploads/doc.pdf">Download</a></div>';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertContains( 22, $ids );
+	}
+
+	public function testVideoBlockWithWpVideoClass() {
+		$content = '<figure class="wp-block-video wp-video-44"><video src="https://example.com/uploads/movie.mp4"></video></figure>';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertContains( 44, $ids );
+	}
+
+	public function testDeduplication() {
+		$content = '<img class="wp-image-5" src="https://example.com/a.jpg" />'
+			. '<img src="https://example.com/b.jpg" class="wp-image-5" />';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 1, $results );
+		$this->assertEquals( 5, $results[0]['attachment_id'] );
+	}
+
+	public function testMultipleAttachments() {
+		$content = '<img class="wp-image-1" src="https://example.com/a.jpg" />'
+			. '<img class="wp-image-2" src="https://example.com/b.jpg" />'
+			. '<img class="wp-image-3" src="https://example.com/c.jpg" />';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$this->assertCount( 3, $results );
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertEquals( [ 1, 2, 3 ], $ids );
+	}
+
+	public function testExtractAttachmentIds() {
+		$content = '<img class="wp-image-10" src="https://example.com/a.jpg" />'
+			. '<img class="wp-image-20" src="https://example.com/b.jpg" />';
+		$ids = Content_Parser\extract_attachment_ids_from_content( $content );
+
+		$this->assertEquals( [ 10, 20 ], $ids );
+	}
+
+	public function testCleanUrlStripsQueryParams() {
+		$url = 'https://example.com/uploads/photo.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test';
+		$clean = Content_Parser\clean_url( $url );
+
+		$this->assertEquals( 'https://example.com/uploads/photo.jpg', $clean );
+	}
+
+	public function testCleanUrlConvertsTachyon() {
+		$url = 'https://example.com/tachyon/uploads/2024/01/photo.jpg';
+		$clean = Content_Parser\clean_url( $url );
+
+		$this->assertEquals( 'https://example.com/wp-content/uploads/2024/01/photo.jpg', $clean );
+	}
+
+	public function testLazyVideoDataSrc() {
+		$content = '<!-- wp:video {"id":99} --><figure class="wp-block-video"><video data-src="https://example.com/uploads/lazy.mp4"></video></figure><!-- /wp:video -->';
+		$results = Content_Parser\extract_attachments_from_content( $content );
+
+		$ids = array_column( $results, 'attachment_id' );
+		$this->assertContains( 99, $ids );
+	}
+}
diff --git a/tests/integration/PrivateMedia/OverrideTest.php b/tests/integration/PrivateMedia/OverrideTest.php
new file mode 100644
index 0000000..5733799
--- /dev/null
+++ b/tests/integration/PrivateMedia/OverrideTest.php
@@ -0,0 +1,107 @@
+<?php
+/**
+ * Test manual override (spec Section 2).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+require_once __DIR__ . '/S3MockTrait.php';
+
+use Altis\Media\Private_Media\Visibility;
+
+class OverrideTest extends \Codeception\TestCase\WPTestCase {
+	use S3MockTrait;
+
+	protected $tester;
+
+	public function setUp() : void {
+		parent::setUp();
+		$this->setup_s3_mock();
+	}
+
+	public function tearDown() : void {
+		$this->teardown_s3_mock();
+		parent::tearDown();
+	}
+
+	public function testForcePublicWithNoReferences() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		Visibility\set_override( $id, 'public' );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+		$this->assertEquals( 'publish', get_post_status( $id ) );
+		$this->assertAclSetTo( $id, 'public-read' );
+	}
+
+	public function testForcePrivateWithReferences() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'publish' ], [
+			'altis_used_in_published_post' => [ 42 ],
+		] );
+
+		Visibility\set_override( $id, 'private' );
+
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ) );
+		$this->assertEquals( 'private', get_post_status( $id ) );
+		$this->assertAclSetTo( $id, 'private' );
+	}
+
+	public function testRemoveOverride() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'publish' ], [
+			'altis_override_visibility' => 'public',
+		] );
+
+		Visibility\set_override( $id, 'auto' );
+
+		$this->assertEquals( 'auto', Visibility\get_override( $id ) );
+		// Without references, should be private.
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testForcePrivateOverridesLegacy() {
+		$id = $this->create_test_attachment( [], [
+			'legacy_attachment' => true,
+			'altis_override_visibility' => 'private',
+		] );
+
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testForcePrivateOverridesSiteIcon() {
+		$id = $this->create_test_attachment( [], [
+			'site_icon' => true,
+			'altis_override_visibility' => 'private',
+		] );
+
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testInvalidOverrideIgnored() {
+		$id = $this->create_test_attachment();
+
+		Visibility\set_override( $id, 'invalid_value' );
+
+		// Should remain auto.
+		$this->assertEquals( 'auto', Visibility\get_override( $id ) );
+	}
+
+	public function testOverrideToAutoRemovesMetadata() {
+		$id = $this->create_test_attachment( [], [
+			'altis_override_visibility' => 'public',
+		] );
+
+		Visibility\set_override( $id, 'auto' );
+
+		$metadata = wp_get_attachment_metadata( $id );
+		if ( is_array( $metadata ) ) {
+			$this->assertArrayNotHasKey( 'altis_override_visibility', $metadata );
+		} else {
+			// No metadata at all means the key is definitely not present.
+			$this->assertTrue( true );
+		}
+	}
+}
diff --git a/tests/integration/PrivateMedia/PostLifecycleTest.php b/tests/integration/PrivateMedia/PostLifecycleTest.php
new file mode 100644
index 0000000..3061026
--- /dev/null
+++ b/tests/integration/PrivateMedia/PostLifecycleTest.php
@@ -0,0 +1,183 @@
+<?php
+/**
+ * Test post lifecycle transitions (spec Section 1).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+require_once __DIR__ . '/S3MockTrait.php';
+
+use Altis\Media\Private_Media\Post_Lifecycle;
+use Altis\Media\Private_Media\Visibility;
+
+class PostLifecycleTest extends \Codeception\TestCase\WPTestCase {
+	use S3MockTrait;
+
+	protected $tester;
+
+	public function setUp() : void {
+		parent::setUp();
+		$this->setup_s3_mock();
+	}
+
+	public function tearDown() : void {
+		$this->teardown_s3_mock();
+		parent::tearDown();
+	}
+
+	public function testPublishMakesAttachmentsPublic() {
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+		$post_id = $this->factory()->post->create( [
+			'post_status'  => 'draft',
+			'post_content' => sprintf( '<img class="wp-image-%d" src="https://example.com/photo.jpg" />', $attachment_id ),
+		] );
+
+		// Publish the post.
+		wp_update_post( [
+			'ID'          => $post_id,
+			'post_status' => 'publish',
+		] );
+
+		$this->assertEquals( 'publish', get_post_status( $attachment_id ) );
+		$this->assertContains( $post_id, Visibility\get_used_in_posts( $attachment_id ) );
+		$this->assertAclSetTo( $attachment_id, 'public-read' );
+	}
+
+	public function testUnpublishMakesAttachmentsPrivate() {
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'publish' ], [
+			'altis_used_in_published_post' => [],
+		] );
+		$post_id = $this->factory()->post->create( [
+			'post_status'  => 'draft',
+			'post_content' => sprintf( '<img class="wp-image-%d" src="https://example.com/photo.jpg" />', $attachment_id ),
+		] );
+
+		// Publish then unpublish.
+		wp_update_post( [ 'ID' => $post_id, 'post_status' => 'publish' ] );
+		$this->acl_calls = []; // Reset calls.
+
+		wp_update_post( [ 'ID' => $post_id, 'post_status' => 'draft' ] );
+
+		$this->assertEquals( 'private', get_post_status( $attachment_id ) );
+		$this->assertEmpty( Visibility\get_used_in_posts( $attachment_id ) );
+		$this->assertAclSetTo( $attachment_id, 'private' );
+	}
+
+	public function testFeaturedImageTransitions() {
+		// Set current user to admin so they can set thumbnails on private attachments.
+		wp_set_current_user( 1 );
+
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+		$post_id = $this->factory()->post->create( [
+			'post_status'  => 'draft',
+			'post_content' => '',
+		] );
+
+		// Use update_post_meta directly since set_post_thumbnail checks caps.
+		update_post_meta( $post_id, '_thumbnail_id', $attachment_id );
+
+		// Publish.
+		wp_update_post( [ 'ID' => $post_id, 'post_status' => 'publish' ] );
+
+		$this->assertEquals( 'publish', get_post_status( $attachment_id ), 'Featured image should become publish.' );
+		$this->assertContains( $post_id, Visibility\get_used_in_posts( $attachment_id ) );
+
+		wp_set_current_user( 0 );
+	}
+
+	public function testMultiPostReferencesKeepPublic() {
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+		$content = sprintf( '<img class="wp-image-%d" src="https://example.com/photo.jpg" />', $attachment_id );
+
+		$post1 = $this->factory()->post->create( [ 'post_status' => 'draft', 'post_content' => $content ] );
+		$post2 = $this->factory()->post->create( [ 'post_status' => 'draft', 'post_content' => $content ] );
+
+		// Publish both.
+		wp_update_post( [ 'ID' => $post1, 'post_status' => 'publish' ] );
+		wp_update_post( [ 'ID' => $post2, 'post_status' => 'publish' ] );
+
+		// Unpublish one — should stay public.
+		wp_update_post( [ 'ID' => $post1, 'post_status' => 'draft' ] );
+
+		$this->assertEquals( 'publish', get_post_status( $attachment_id ) );
+		$this->assertContains( $post2, Visibility\get_used_in_posts( $attachment_id ) );
+	}
+
+	public function testRemovedAttachmentDetection() {
+		$att1 = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+		$att2 = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		$content_both = sprintf(
+			'<img class="wp-image-%d" src="https://example.com/a.jpg" /><img class="wp-image-%d" src="https://example.com/b.jpg" />',
+			$att1,
+			$att2
+		);
+
+		$post_id = $this->factory()->post->create( [
+			'post_status'  => 'publish',
+			'post_content' => $content_both,
+		] );
+
+		// Both should be public now.
+		// Force the lifecycle to process (since the post was created as publish).
+		Post_Lifecycle\handle_publish( get_post( $post_id ) );
+
+		$this->assertEquals( 'publish', get_post_status( $att1 ) );
+		$this->assertEquals( 'publish', get_post_status( $att2 ) );
+
+		// Remove att2 from content and resave.
+		$content_one = sprintf( '<img class="wp-image-%d" src="https://example.com/a.jpg" />', $att1 );
+		wp_update_post( [ 'ID' => $post_id, 'post_content' => $content_one ] );
+
+		// Manually call resave handler since save_post fires during transition_post_status context.
+		Post_Lifecycle\handle_resave( get_post( $post_id ) );
+
+		$this->assertEquals( 'publish', get_post_status( $att1 ), 'att1 should still be public.' );
+		$this->assertEquals( 'private', get_post_status( $att2 ), 'att2 should now be private.' );
+	}
+
+	public function testFilterExtensibility() {
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		// Register a custom meta key.
+		add_filter( 'private_media/post_meta_attachment_keys', function ( $keys ) {
+			$keys[] = '_custom_image_id';
+			return $keys;
+		} );
+
+		$post_id = $this->factory()->post->create( [
+			'post_status'  => 'draft',
+			'post_content' => '',
+		] );
+
+		update_post_meta( $post_id, '_custom_image_id', $attachment_id );
+
+		wp_update_post( [ 'ID' => $post_id, 'post_status' => 'publish' ] );
+
+		$this->assertEquals( 'publish', get_post_status( $attachment_id ) );
+
+		// Clean up.
+		remove_all_filters( 'private_media/post_meta_attachment_keys' );
+	}
+
+	public function testIsAllowedPostType() {
+		$this->assertTrue( Post_Lifecycle\is_allowed_post_type( 'post' ) );
+		$this->assertTrue( Post_Lifecycle\is_allowed_post_type( 'page' ) );
+		$this->assertFalse( Post_Lifecycle\is_allowed_post_type( 'attachment' ) );
+	}
+
+	public function testAllowedPostTypesFilter() {
+		add_filter( 'private_media/allowed_post_types', function ( $types ) {
+			$types[] = 'custom_type';
+			return $types;
+		} );
+
+		$this->assertTrue( Post_Lifecycle\is_allowed_post_type( 'custom_type' ) );
+
+		remove_all_filters( 'private_media/allowed_post_types' );
+	}
+}
diff --git a/tests/integration/PrivateMedia/QueryCompatTest.php b/tests/integration/PrivateMedia/QueryCompatTest.php
new file mode 100644
index 0000000..e38b743
--- /dev/null
+++ b/tests/integration/PrivateMedia/QueryCompatTest.php
@@ -0,0 +1,105 @@
+<?php
+/**
+ * Test attachment query compatibility (spec Section 9).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+use Altis\Media\Private_Media\Query_Compat;
+
+class QueryCompatTest extends \Codeception\TestCase\WPTestCase {
+
+	protected $tester;
+
+	public function testInheritExpandedForAttachmentQueries() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'attachment' );
+		$query->set( 'post_status', 'inherit' );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$this->assertIsArray( $status );
+		$this->assertContains( 'inherit', $status );
+		$this->assertContains( 'publish', $status );
+		$this->assertContains( 'private', $status );
+	}
+
+	public function testArrayStatusExpanded() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'attachment' );
+		$query->set( 'post_status', [ 'inherit' ] );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$this->assertContains( 'publish', $status );
+		$this->assertContains( 'private', $status );
+	}
+
+	public function testNonAttachmentQueryUnaffected() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'post' );
+		$query->set( 'post_status', 'inherit' );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		// Should remain unchanged.
+		$this->assertEquals( 'inherit', $query->get( 'post_status' ) );
+	}
+
+	public function testNonInheritStatusUnaffected() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'attachment' );
+		$query->set( 'post_status', [ 'publish' ] );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$this->assertNotContains( 'private', $status );
+	}
+
+	public function testNoDuplicateStatuses() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'attachment' );
+		$query->set( 'post_status', [ 'inherit', 'publish' ] );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$publish_count = count( array_filter( $status, function ( $s ) {
+			return $s === 'publish';
+		} ) );
+		$this->assertEquals( 1, $publish_count );
+	}
+
+	public function testEmptyStatusDefaultsToInherit() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', 'attachment' );
+		// Don't set post_status — should default to treating as inherit.
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$this->assertIsArray( $status );
+		$this->assertContains( 'inherit', $status );
+		$this->assertContains( 'publish', $status );
+		$this->assertContains( 'private', $status );
+	}
+
+	public function testAttachmentInArrayPostType() {
+		$query = new \WP_Query();
+		$query->set( 'post_type', [ 'post', 'attachment' ] );
+		$query->set( 'post_status', 'inherit' );
+
+		Query_Compat\filter_attachment_query( $query );
+
+		$status = $query->get( 'post_status' );
+		$this->assertIsArray( $status );
+		$this->assertContains( 'publish', $status );
+	}
+}
diff --git a/tests/integration/PrivateMedia/S3MockTrait.php b/tests/integration/PrivateMedia/S3MockTrait.php
new file mode 100644
index 0000000..c379447
--- /dev/null
+++ b/tests/integration/PrivateMedia/S3MockTrait.php
@@ -0,0 +1,117 @@
+<?php
+/**
+ * Trait for mocking S3 ACL operations in tests.
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+/**
+ * Provides S3 ACL mocking for private media tests.
+ *
+ * Usage: Use this trait in your test class, and call $this->setup_s3_mock()
+ * in your setUp() method.
+ */
+trait S3MockTrait {
+	/**
+	 * Recorded ACL calls: [ attachment_id => acl ].
+	 *
+	 * @var array<int, string>
+	 */
+	protected array $acl_calls = [];
+
+	/**
+	 * Recorded CDN purge calls: [ attachment_id, ... ].
+	 *
+	 * @var int[]
+	 */
+	protected array $cdn_purge_calls = [];
+
+	/**
+	 * Set up S3 mock filters.
+	 *
+	 * @return void
+	 */
+	protected function setup_s3_mock() : void {
+		$this->acl_calls = [];
+		$this->cdn_purge_calls = [];
+
+		add_filter( 'private_media/update_s3_acl', function ( $result, $attachment_id, $acl ) {
+			$this->acl_calls[ $attachment_id ] = $acl;
+			return true; // Short-circuit real S3 call.
+		}, 10, 3 );
+
+		add_filter( 'private_media/purge_cdn_cache', function ( $result, $attachment_id ) {
+			$this->cdn_purge_calls[] = $attachment_id;
+			return true; // Short-circuit.
+		}, 10, 2 );
+	}
+
+	/**
+	 * Assert that the ACL was set to a specific value for an attachment.
+	 *
+	 * @param int    $attachment_id The attachment ID.
+	 * @param string $expected_acl  The expected ACL value.
+	 * @return void
+	 */
+	protected function assertAclSetTo( int $attachment_id, string $expected_acl ) : void {
+		$this->assertArrayHasKey( $attachment_id, $this->acl_calls, "ACL was not set for attachment {$attachment_id}." );
+		$this->assertEquals( $expected_acl, $this->acl_calls[ $attachment_id ], "ACL for attachment {$attachment_id} was not set to {$expected_acl}." );
+	}
+
+	/**
+	 * Assert that the ACL was NOT called for an attachment.
+	 *
+	 * @param int $attachment_id The attachment ID.
+	 * @return void
+	 */
+	protected function assertAclNotCalled( int $attachment_id ) : void {
+		$this->assertArrayNotHasKey( $attachment_id, $this->acl_calls, "ACL was unexpectedly called for attachment {$attachment_id}." );
+	}
+
+	/**
+	 * Create a test attachment with optional metadata.
+	 *
+	 * @param array $args     Optional post args.
+	 * @param array $metadata Optional metadata to set.
+	 * @return int The created attachment ID.
+	 */
+	protected function create_test_attachment( array $args = [], array $metadata = [] ) : int {
+		$defaults = [
+			'post_type'   => 'attachment',
+			'post_status' => 'inherit',
+			'post_title'  => 'Test Attachment',
+			'post_mime_type' => 'image/jpeg',
+		];
+
+		// Remove the private-by-default hook temporarily so we can set our own status.
+		remove_action( 'add_attachment', 'Altis\\Media\\Private_Media\\Visibility\\set_new_attachment_private' );
+
+		$id = wp_insert_attachment( array_merge( $defaults, $args ) );
+
+		// Re-add the hook.
+		add_action( 'add_attachment', 'Altis\\Media\\Private_Media\\Visibility\\set_new_attachment_private' );
+
+		if ( ! empty( $metadata ) ) {
+			wp_update_attachment_metadata( $id, $metadata );
+		}
+
+		// Reset ACL calls from creation.
+		unset( $this->acl_calls[ $id ] );
+
+		return $id;
+	}
+
+	/**
+	 * Tear down S3 mock filters.
+	 *
+	 * @return void
+	 */
+	protected function teardown_s3_mock() : void {
+		remove_all_filters( 'private_media/update_s3_acl' );
+		remove_all_filters( 'private_media/purge_cdn_cache' );
+	}
+}
diff --git a/tests/integration/PrivateMedia/SanitisationTest.php b/tests/integration/PrivateMedia/SanitisationTest.php
new file mode 100644
index 0000000..d25bfaa
--- /dev/null
+++ b/tests/integration/PrivateMedia/SanitisationTest.php
@@ -0,0 +1,115 @@
+<?php
+/**
+ * Test content sanitisation (spec Section 6).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+use Altis\Media\Private_Media\Sanitisation;
+
+class SanitisationTest extends \Codeception\TestCase\WPTestCase {
+
+	protected $tester;
+
+	public function testStripsAllAwsParams() {
+		$params = [
+			'X-Amz-Content-Sha256=abc',
+			'X-Amz-Security-Token=def',
+			'X-Amz-Algorithm=AWS4-HMAC-SHA256',
+			'X-Amz-Credential=AKID/20240101/us-east-1/s3/aws4_request',
+			'X-Amz-Date=20240101T000000Z',
+			'X-Amz-SignedHeaders=host',
+			'X-Amz-Expires=900',
+			'X-Amz-Signature=abc123',
+			'presign=true',
+		];
+
+		$url = 'https://example.com/uploads/photo.jpg?' . implode( '&', $params );
+		$content = sprintf( '<img src="%s" class="wp-image-1" />', $url );
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		foreach ( Sanitisation\AWS_PARAMS as $param ) {
+			$this->assertStringNotContainsString( $param, $result, "Parameter {$param} should be stripped." );
+		}
+
+		$this->assertStringContainsString( 'photo.jpg', $result );
+	}
+
+	public function testPreservesNonAwsQueryParams() {
+		$url = 'https://example.com/uploads/photo.jpg?w=800&h=600&X-Amz-Algorithm=test&quality=80';
+		$content = sprintf( '<img src="%s" />', $url );
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		$this->assertStringContainsString( 'w=800', $result );
+		$this->assertStringContainsString( 'h=600', $result );
+		$this->assertStringContainsString( 'quality=80', $result );
+		$this->assertStringNotContainsString( 'X-Amz-Algorithm', $result );
+	}
+
+	public function testStripsFromHrefAttribute() {
+		$url = 'https://example.com/uploads/doc.pdf?X-Amz-Signature=abc&presign=true';
+		$content = sprintf( '<a href="%s">Download</a>', $url );
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		$this->assertStringNotContainsString( 'X-Amz-Signature', $result );
+		$this->assertStringNotContainsString( 'presign', $result );
+		$this->assertStringContainsString( 'doc.pdf', $result );
+	}
+
+	public function testStripsFromDataSrcAttribute() {
+		$url = 'https://example.com/uploads/video.mp4?X-Amz-Algorithm=test';
+		$content = sprintf( '<video data-src="%s"></video>', $url );
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		$this->assertStringNotContainsString( 'X-Amz-Algorithm', $result );
+	}
+
+	public function testMixedUrls() {
+		$content = '<img src="https://example.com/a.jpg?X-Amz-Signature=abc" class="wp-image-1" />'
+			. '<img src="https://example.com/b.jpg" class="wp-image-2" />'
+			. '<a href="https://example.com/c.pdf?presign=true&X-Amz-Date=20240101">PDF</a>';
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		$this->assertStringNotContainsString( 'X-Amz-Signature', $result );
+		$this->assertStringNotContainsString( 'presign', $result );
+		$this->assertStringNotContainsString( 'X-Amz-Date', $result );
+		$this->assertStringContainsString( 'a.jpg', $result );
+		$this->assertStringContainsString( 'b.jpg', $result );
+		$this->assertStringContainsString( 'c.pdf', $result );
+	}
+
+	public function testSanitisePostContentFilter() {
+		$data = [
+			'post_content' => '<img src="https://example.com/a.jpg?X-Amz-Algorithm=test" />',
+		];
+
+		$result = Sanitisation\sanitise_post_content( $data );
+
+		$this->assertStringNotContainsString( 'X-Amz-Algorithm', $result['post_content'] );
+	}
+
+	public function testEmptyContentPassesThrough() {
+		$data = [ 'post_content' => '' ];
+		$result = Sanitisation\sanitise_post_content( $data );
+		$this->assertEquals( '', $result['post_content'] );
+	}
+
+	public function testStripsXAmzS3HostParam() {
+		$url = 'https://example.com/uploads/photo.jpg?X-Amz-S3-Host=s3.amazonaws.com&w=800';
+		$content = sprintf( '<img src="%s" />', $url );
+
+		$result = Sanitisation\strip_aws_params_from_content( $content );
+
+		$this->assertStringNotContainsString( 'X-Amz-S3-Host', $result );
+		$this->assertStringContainsString( 'w=800', $result );
+	}
+}
diff --git a/tests/integration/PrivateMedia/SignedUrlsTest.php b/tests/integration/PrivateMedia/SignedUrlsTest.php
new file mode 100644
index 0000000..b38ccd7
--- /dev/null
+++ b/tests/integration/PrivateMedia/SignedUrlsTest.php
@@ -0,0 +1,64 @@
+<?php
+/**
+ * Test signed URL previews (spec Section 5).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+require_once __DIR__ . '/S3MockTrait.php';
+
+use Altis\Media\Private_Media\Signed_Urls;
+
+class SignedUrlsTest extends \Codeception\TestCase\WPTestCase {
+	use S3MockTrait;
+
+	protected $tester;
+
+	public function setUp() : void {
+		parent::setUp();
+		$this->setup_s3_mock();
+	}
+
+	public function tearDown() : void {
+		$this->teardown_s3_mock();
+		parent::tearDown();
+	}
+
+	public function testSrcsetDisabledInPreview() {
+		// Simulate preview context.
+		$GLOBALS['wp_query'] = new \WP_Query();
+		$GLOBALS['wp_query']->is_preview = true;
+
+		$sources = [
+			300 => [ 'url' => 'https://example.com/photo-300.jpg', 'descriptor' => 'w', 'value' => 300 ],
+			600 => [ 'url' => 'https://example.com/photo-600.jpg', 'descriptor' => 'w', 'value' => 600 ],
+		];
+
+		$result = Signed_Urls\disable_srcset_in_preview( $sources );
+		$this->assertEmpty( $result );
+
+		// Reset.
+		$GLOBALS['wp_query']->is_preview = false;
+	}
+
+	public function testSrcsetPreservedNormally() {
+		$sources = [
+			300 => [ 'url' => 'https://example.com/photo-300.jpg', 'descriptor' => 'w', 'value' => 300 ],
+		];
+
+		$result = Signed_Urls\disable_srcset_in_preview( $sources );
+		$this->assertEquals( $sources, $result );
+	}
+
+	public function testNonPreviewContentUnchanged() {
+		$content = '<img class="wp-image-1" src="https://example.com/photo.jpg" />';
+
+		// Not in preview mode.
+		$result = Signed_Urls\replace_private_urls_in_preview( $content );
+		$this->assertEquals( $content, $result );
+	}
+}
diff --git a/tests/integration/PrivateMedia/SiteIconTest.php b/tests/integration/PrivateMedia/SiteIconTest.php
new file mode 100644
index 0000000..3f46adf
--- /dev/null
+++ b/tests/integration/PrivateMedia/SiteIconTest.php
@@ -0,0 +1,71 @@
+<?php
+/**
+ * Test site icon handling (spec Section 12).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+require_once __DIR__ . '/S3MockTrait.php';
+
+use Altis\Media\Private_Media\Site_Icon;
+use Altis\Media\Private_Media\Visibility;
+
+class SiteIconTest extends \Codeception\TestCase\WPTestCase {
+	use S3MockTrait;
+
+	protected $tester;
+
+	public function setUp() : void {
+		parent::setUp();
+		$this->setup_s3_mock();
+	}
+
+	public function tearDown() : void {
+		$this->teardown_s3_mock();
+		// Reset site_icon option.
+		delete_option( 'site_icon' );
+		parent::tearDown();
+	}
+
+	public function testSiteIconMarkedPublic() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		// Simulate updating the site_icon option.
+		Site_Icon\on_site_icon_update( 0, $id );
+
+		$metadata = wp_get_attachment_metadata( $id );
+		$this->assertTrue( $metadata['site_icon'] ?? false );
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testOldSiteIconCleared() {
+		$old_id = $this->create_test_attachment( [], [ 'site_icon' => true ] );
+		$new_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		Site_Icon\on_site_icon_update( $old_id, $new_id );
+
+		// Old icon should have site_icon cleared.
+		$old_metadata = wp_get_attachment_metadata( $old_id );
+		$this->assertTrue( ! is_array( $old_metadata ) || ! isset( $old_metadata['site_icon'] ), 'site_icon should be removed from old icon metadata.' );
+
+		// New icon should have site_icon set.
+		$new_metadata = wp_get_attachment_metadata( $new_id );
+		$this->assertTrue( $new_metadata['site_icon'] ?? false );
+	}
+
+	public function testSiteIconAlwaysPublic() {
+		$id = $this->create_test_attachment( [], [ 'site_icon' => true ] );
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testSiteIconOptionFallback() {
+		$id = $this->create_test_attachment();
+		update_option( 'site_icon', $id );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+}
diff --git a/tests/integration/PrivateMedia/VisibilityTest.php b/tests/integration/PrivateMedia/VisibilityTest.php
new file mode 100644
index 0000000..0f0266f
--- /dev/null
+++ b/tests/integration/PrivateMedia/VisibilityTest.php
@@ -0,0 +1,196 @@
+<?php
+/**
+ * Test visibility priority logic (spec Section 3).
+ *
+ * phpcs:disable WordPress.Files, HM.Files, HM.Functions.NamespacedFunctions, WordPress.NamingConventions
+ *
+ * @package altis/media
+ */
+
+namespace PrivateMedia;
+
+require_once __DIR__ . '/S3MockTrait.php';
+
+use Altis\Media\Private_Media\Visibility;
+
+class VisibilityTest extends \Codeception\TestCase\WPTestCase {
+	use S3MockTrait;
+
+	protected $tester;
+
+	public function setUp() : void {
+		parent::setUp();
+		$this->setup_s3_mock();
+	}
+
+	public function tearDown() : void {
+		$this->teardown_s3_mock();
+		parent::tearDown();
+	}
+
+	public function testDefaultIsPrivate() {
+		$id = $this->create_test_attachment();
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testForcePrivateOverrideTakesPrecedence() {
+		$id = $this->create_test_attachment( [], [
+			'altis_override_visibility' => 'private',
+			'altis_used_in_published_post' => [ 999 ],
+		] );
+
+		$this->assertFalse( Visibility\check_attachment_is_public( $id ), 'Force-private should override used-in-post.' );
+	}
+
+	public function testForcePublicOverride() {
+		$id = $this->create_test_attachment( [], [
+			'altis_override_visibility' => 'public',
+		] );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testUsedInPublishedPostIsPublic() {
+		$id = $this->create_test_attachment( [], [
+			'altis_used_in_published_post' => [ 42 ],
+		] );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testLegacyAttachmentIsPublic() {
+		$id = $this->create_test_attachment( [], [
+			'legacy_attachment' => true,
+		] );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testSiteIconMetadataIsPublic() {
+		$id = $this->create_test_attachment( [], [
+			'site_icon' => true,
+		] );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+	}
+
+	public function testSiteIconOptionFallback() {
+		$id = $this->create_test_attachment();
+		update_option( 'site_icon', $id );
+
+		$this->assertTrue( Visibility\check_attachment_is_public( $id ) );
+
+		// Clean up.
+		delete_option( 'site_icon' );
+	}
+
+	public function testSetAttachmentVisibilityUpdatesStatus() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'private' ], [
+			'altis_override_visibility' => 'public',
+		] );
+
+		Visibility\set_attachment_visibility( $id );
+
+		$this->assertEquals( 'publish', get_post_status( $id ) );
+		$this->assertAclSetTo( $id, 'public-read' );
+	}
+
+	public function testSetAttachmentVisibilityToPrivate() {
+		$id = $this->create_test_attachment( [ 'post_status' => 'publish' ] );
+
+		Visibility\set_attachment_visibility( $id );
+
+		$this->assertEquals( 'private', get_post_status( $id ) );
+		$this->assertAclSetTo( $id, 'private' );
+	}
+
+	public function testGetOverrideDefaultsToAuto() {
+		$id = $this->create_test_attachment();
+		$this->assertEquals( 'auto', Visibility\get_override( $id ) );
+	}
+
+	public function testSetOverride() {
+		$id = $this->create_test_attachment();
+
+		Visibility\set_override( $id, 'public' );
+		$this->assertEquals( 'public', Visibility\get_override( $id ) );
+
+		Visibility\set_override( $id, 'private' );
+		$this->assertEquals( 'private', Visibility\get_override( $id ) );
+
+		Visibility\set_override( $id, 'auto' );
+		$this->assertEquals( 'auto', Visibility\get_override( $id ) );
+	}
+
+	public function testSetOverrideInvalidValueIgnored() {
+		$id = $this->create_test_attachment( [], [
+			'altis_override_visibility' => 'public',
+		] );
+
+		Visibility\set_override( $id, 'invalid' );
+		$this->assertEquals( 'public', Visibility\get_override( $id ) );
+	}
+
+	public function testPostReferenceTracking() {
+		$id = $this->create_test_attachment();
+
+		$this->assertEmpty( Visibility\get_used_in_posts( $id ) );
+
+		Visibility\add_post_reference( $id, 100 );
+		$this->assertEquals( [ 100 ], Visibility\get_used_in_posts( $id ) );
+
+		Visibility\add_post_reference( $id, 200 );
+		$this->assertEquals( [ 100, 200 ], Visibility\get_used_in_posts( $id ) );
+
+		// Duplicate add should not create duplicate.
+		Visibility\add_post_reference( $id, 100 );
+		$this->assertEquals( [ 100, 200 ], Visibility\get_used_in_posts( $id ) );
+
+		Visibility\remove_post_reference( $id, 100 );
+		$this->assertEquals( [ 200 ], Visibility\get_used_in_posts( $id ) );
+
+		Visibility\remove_post_reference( $id, 200 );
+		$this->assertEmpty( Visibility\get_used_in_posts( $id ) );
+	}
+
+	public function testNewAttachmentDefaultsToPrivate() {
+		// Test the add_attachment hook directly.
+		$id = wp_insert_attachment( [
+			'post_type'      => 'attachment',
+			'post_title'     => 'New Upload',
+			'post_mime_type' => 'image/jpeg',
+			'post_status'    => 'inherit',
+		] );
+
+		$this->assertEquals( 'private', get_post_status( $id ) );
+		$this->assertAclSetTo( $id, 'private' );
+	}
+
+	public function testAuthorCanReadPrivateAttachment() {
+		$author_id = $this->factory()->user->create( [ 'role' => 'author' ] );
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		wp_set_current_user( $author_id );
+
+		// Authors have upload_files, so they should be able to read private attachments.
+		$this->assertTrue( current_user_can( 'read_post', $attachment_id ), 'Author should be able to read private attachments.' );
+
+		// wp_get_attachment_url should work for private attachments.
+		$url = wp_get_attachment_url( $attachment_id );
+		$this->assertNotFalse( $url, 'wp_get_attachment_url should work for authors with private attachments.' );
+
+		wp_set_current_user( 0 );
+	}
+
+	public function testSubscriberCannotReadPrivateAttachment() {
+		$subscriber_id = $this->factory()->user->create( [ 'role' => 'subscriber' ] );
+		$attachment_id = $this->create_test_attachment( [ 'post_status' => 'private' ] );
+
+		wp_set_current_user( $subscriber_id );
+
+		// Subscribers don't have upload_files, so they should NOT be able to read.
+		$this->assertFalse( current_user_can( 'read_post', $attachment_id ), 'Subscriber should not be able to read private attachments.' );
+
+		wp_set_current_user( 0 );
+	}
+}