diff --git a/apps/staged/docs/inline-note-media.md b/apps/staged/docs/inline-note-media.md
index e3d30ae6e..be20efcd3 100644
--- a/apps/staged/docs/inline-note-media.md
+++ b/apps/staged/docs/inline-note-media.md
@@ -41,10 +41,24 @@ the current webview. Older QuickTime files without an `ftyp` header are rejected
 Chat attachments (file picker, paste, drop) share the validation code but are
 stored under the format their bytes actually are: browsers label `file.type`
 from the filename, so a WebP saved as `shot.png` is stored as `shot.webp` with
-an `image/webp` MIME rather than rejected. Only unrecognized signatures, videos,
-and oversized files are refused, and the composer shows the reason for pasted,
-picked, and natively dropped files alike, clearing it when the message is sent
-or the attachment removed.
+an `image/webp` MIME rather than rejected. A dropped, pasted, or picked PDF (up
+to 50 MiB) is stored byte-for-byte as `application/pdf` so the viewer can open
+it in the webview's native PDF viewer (vector zoom, every page) from its served
+media URL (`staged-media://<uuid>.pdf`, `/api/media/<uuid>.pdf` in web mode,
+where the response omits the `sandbox` CSP directive that would blank WebKit's
+viewer); thumbnails show its first page, rendered once with CoreGraphics on
+macOS and written atomically as `<uuid>.thumb.png` beside the file, and the
+agent prompt gets its pages as captioned image blocks, since the ACP agents
+accept only image blocks: up to 20 pages per PDF, within a 20 MB budget of
+encoded images that the whole message's attachments share (an image or page
+that would cross it is named in the prompt text), each page at most 5 MB (PNG,
+re-rendered at half scale and then re-encoded as JPEG if it has to be), with
+the pages left out named on the last one sent. A `.pdf`
+reference in a note is still refused. Only
+unrecognized signatures, videos, oversized files, and PDFs CoreGraphics cannot
+open are refused, and the composer shows the reason for pasted, picked, and
+natively dropped files alike, clearing it when the message is sent or the
+attachment removed.
 
 On session completion, files are copied into the existing project `images/`
 store and destinations become `staged-media://<uuid>.<ext>`. Captions and titles
diff --git a/apps/staged/src-tauri/Cargo.lock b/apps/staged/src-tauri/Cargo.lock
index 687682319..d619aef7c 100644
--- a/apps/staged/src-tauri/Cargo.lock
+++ b/apps/staged/src-tauri/Cargo.lock
@@ -20,9 +20,12 @@ dependencies = [
  "flate2",
  "git-diff",
  "hex",
+ "image",
  "include_dir",
  "libc",
  "log",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
  "pikchr",
  "rand 0.10.3",
  "regex",
@@ -2537,6 +2540,8 @@ dependencies = [
  "num-traits",
  "png 0.18.1",
  "tiff",
+ "zune-core",
+ "zune-jpeg",
 ]
 
 [[package]]
diff --git a/apps/staged/src-tauri/Cargo.toml b/apps/staged/src-tauri/Cargo.toml
index b33d73b8c..370f4d954 100644
--- a/apps/staged/src-tauri/Cargo.toml
+++ b/apps/staged/src-tauri/Cargo.toml
@@ -85,6 +85,29 @@ tiny-skia = "0.12"
 tar = "0.4"
 flate2 = "1"
 
+# PDF attachments: rasterize pages with CoreGraphics (note_media::pdf). All
+# three crates are already in the lock via arboard/tray-icon (and `image`'s
+# jpeg feature only adds zune-jpeg, which resvg pulls in); the feature lists
+# are the minimum for CGPDFDocument + a bitmap CGContext + CFData input, and
+# a JPEG encoder for prompt pages whose PNG is over the per-image cap.
+[target.'cfg(target_os = "macos")'.dependencies]
+image = { version = "0.25", default-features = false, features = ["jpeg"] }
+objc2-core-graphics = { version = "0.3.2", default-features = false, features = [
+    "CGAffineTransform",
+    "CGBitmapContext",
+    "CGColorSpace",
+    "CGContext",
+    "CGDataProvider",
+    "CGGeometry",
+    "CGImage",
+    "CGPDFDocument",
+    "CGPDFPage",
+] }
+objc2-core-foundation = { version = "0.3.2", default-features = false, features = [
+    "CFCGTypes",
+    "CFData",
+] }
+
 [dev-dependencies]
 tower = { version = "0.5", features = ["util"] }
 # test-util: `#[tokio::test(start_paused = true)]` for the store-events
diff --git a/apps/staged/src-tauri/src/branches.rs b/apps/staged/src-tauri/src/branches.rs
index 87487025b..6b25be8d9 100644
--- a/apps/staged/src-tauri/src/branches.rs
+++ b/apps/staged/src-tauri/src/branches.rs
@@ -2679,6 +2679,21 @@ fn move_branch_image_files(
         let (Ok(from), Ok(to)) = (from, to) else {
             continue;
         };
+        // A PDF's cached thumbnail travels with it; losing one only costs a
+        // re-render, so its failure is not worth more than a log line.
+        if let (Ok(thumb_from), Ok(thumb_to)) = (
+            store::images::thumbnail_file_path(source_project_id, &image.id),
+            store::images::thumbnail_file_path(target_project_id, &image.id),
+        ) {
+            if thumb_from.exists() {
+                if let Some(parent) = thumb_to.parent() {
+                    let _ = std::fs::create_dir_all(parent);
+                }
+                if let Err(e) = std::fs::rename(&thumb_from, &thumb_to) {
+                    log::warn!("Failed to move thumbnail {}: {e}", thumb_from.display());
+                }
+            }
+        }
         if !from.exists() {
             continue;
         }
diff --git a/apps/staged/src-tauri/src/image_commands.rs b/apps/staged/src-tauri/src/image_commands.rs
index 921d98d73..97ef66495 100644
--- a/apps/staged/src-tauri/src/image_commands.rs
+++ b/apps/staged/src-tauri/src/image_commands.rs
@@ -1,6 +1,8 @@
 //! Image commands — image upload, retrieval, and management.
 
+mod thumbnail;
 mod tool_results;
+pub use thumbnail::*;
 pub use tool_results::*;
 
 use crate::store::Store;
@@ -14,7 +16,7 @@ use std::sync::{Arc, Mutex};
 /// real session ID).  Pass `false` for images that should appear in the
 /// timeline immediately (e.g. direct branch-card drops).
 #[tauri::command(rename_all = "camelCase")]
-pub fn create_image(
+pub async fn create_image(
     store: tauri::State<'_, Mutex<Option<Arc<Store>>>>,
     branch_id: Option<String>,
     project_id: String,
@@ -22,14 +24,27 @@ pub fn create_image(
     pending: Option<bool>,
 ) -> Result<crate::store::Image, String> {
     let store = crate::get_store(&store)?;
+    // Reading and validating a 50 MB PDF is not main-thread work.
+    tauri::async_runtime::spawn_blocking(move || {
+        create_image_impl(store, branch_id, project_id, file_path, pending)
+    })
+    .await
+    .map_err(|e| format!("Failed to store image: {e}"))?
+}
 
+fn create_image_impl(
+    store: Arc<Store>,
+    branch_id: Option<String>,
+    project_id: String,
+    file_path: String,
+    pending: Option<bool>,
+) -> Result<crate::store::Image, String> {
     let src = Path::new(&file_path);
     let filename = src
         .file_name()
         .and_then(|n| n.to_str())
         .ok_or("Invalid filename")?;
-    let bytes =
-        crate::note_media::files::read_local(src, crate::note_media::files::MAX_IMAGE_SIZE)?;
+    let bytes = crate::note_media::files::read_local_attachment(src)?;
     crate::note_media::files::store_sniffed_image(
         &store,
         branch_id.as_deref(),
@@ -73,18 +88,25 @@ pub fn delete_image(
     // Delete the DB record first (triggers session cleanup).
     store.delete_image(&image_id).map_err(|e| e.to_string())?;
 
-    // Best-effort file removal.
-    if let Ok(path) =
-        crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)
-    {
-        if let Err(e) = std::fs::remove_file(&path) {
-            log::warn!("Failed to remove image file {}: {e}", path.display());
-        }
-    }
+    // Best-effort removal of the file and any cached PDF thumbnail.
+    crate::store::images::remove_image_files(&image.project_id, &image.id, &image.filename);
 
     Ok(())
 }
 
+/// A small preview of an attachment: the image itself, or for a PDF a PNG of
+/// its first page, rendered on first use and cached beside the file.
+#[tauri::command(rename_all = "camelCase")]
+pub async fn get_attachment_thumbnail(
+    store: tauri::State<'_, Mutex<Option<Arc<Store>>>>,
+    image_id: String,
+) -> Result<AttachmentThumbnail, String> {
+    let store = crate::get_store(&store)?;
+    tauri::async_runtime::spawn_blocking(move || attachment_thumbnail_impl(&store, &image_id))
+        .await
+        .map_err(|e| format!("Failed to load thumbnail: {e}"))?
+}
+
 /// List all images for a branch.
 #[tauri::command(rename_all = "camelCase")]
 pub fn list_branch_images(
@@ -121,7 +143,7 @@ pub fn get_image_data(
 /// the stored format follows the file signature. See [`create_image`] for the
 /// meaning of the `pending` flag.
 #[tauri::command(rename_all = "camelCase")]
-pub fn create_image_from_data(
+pub async fn create_image_from_data(
     store: tauri::State<'_, Mutex<Option<Arc<Store>>>>,
     branch_id: Option<String>,
     project_id: String,
@@ -131,9 +153,14 @@ pub fn create_image_from_data(
     pending: Option<bool>,
 ) -> Result<crate::store::Image, String> {
     let store = crate::get_store(&store)?;
-    create_image_from_data_impl(
-        store, branch_id, project_id, filename, mime_type, data, pending,
-    )
+    // See `create_image`: decoding a large payload must not block the main thread.
+    tauri::async_runtime::spawn_blocking(move || {
+        create_image_from_data_impl(
+            store, branch_id, project_id, filename, mime_type, data, pending,
+        )
+    })
+    .await
+    .map_err(|e| format!("Failed to store image: {e}"))?
 }
 
 pub(crate) fn create_image_from_data_impl(
@@ -146,10 +173,19 @@ pub(crate) fn create_image_from_data_impl(
     pending: Option<bool>,
 ) -> Result<crate::store::Image, String> {
     use base64::Engine;
-    if data.len() as u64 > crate::note_media::files::MAX_IMAGE_SIZE.div_ceil(3) * 4 {
-        return Err("Image too large (max 10 MB)".into());
+    let engine = base64::engine::general_purpose::STANDARD;
+    // The cap depends on the payload (a PDF may be larger than an image), so
+    // peek at the first six bytes — two base64 quanta — before decoding a
+    // payload that may turn out to be oversized.
+    let header = data
+        .get(..8)
+        .and_then(|quanta| engine.decode(quanta).ok())
+        .unwrap_or_default();
+    let (cap, what) = crate::note_media::files::attachment_limit(&header);
+    if data.len() as u64 > cap.div_ceil(3) * 4 {
+        return Err(crate::note_media::files::size_error(what, cap));
     }
-    let bytes = base64::engine::general_purpose::STANDARD
+    let bytes = engine
         .decode(&data)
         .map_err(|e| format!("Invalid base64 data: {e}"))?;
 
@@ -219,4 +255,130 @@ mod tests {
         let err = attach(&f, "clip.png", "", b"\0\0\0\x18ftypisom\0\0\0\0").unwrap_err();
         assert!(err.contains("only images"), "{err}");
     }
+
+    #[test]
+    fn pdf_attachments_are_stored_as_pdfs() {
+        use crate::note_media::pdf::tests::{tiny_pdf, PAGE_ONE};
+        let f = Fixture::new();
+        let pdf = tiny_pdf(&[PAGE_ONE]);
+        let image = attach(&f, "doc.pdf", "application/pdf", &pdf).unwrap();
+        assert_eq!(image.mime_type, "application/pdf");
+        assert_eq!(image.filename, "doc.pdf");
+        assert_eq!(image.size_bytes, pdf.len() as i64);
+        let path =
+            crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)
+                .unwrap();
+        assert_eq!(path.extension().unwrap(), "pdf");
+        assert_eq!(std::fs::read(path).unwrap(), pdf);
+
+        // Pasted PDFs arrive without a usable name, like pasted images, and a
+        // mislabelled one takes the extension its bytes call for.
+        assert_eq!(
+            attach(&f, "pasted", "application/pdf", &pdf)
+                .unwrap()
+                .filename,
+            "pasted.pdf"
+        );
+        assert_eq!(
+            attach(&f, "scan.png", "image/png", &pdf).unwrap().filename,
+            "scan.pdf"
+        );
+    }
+
+    /// PDFs get the larger input cap on both routes; images keep theirs. The
+    /// padded PDFs here are well-formed, so acceptance means the PDF passed
+    /// the open check, not that the bytes merely got past the size check.
+    #[test]
+    fn pdf_input_cap_is_separate_from_the_image_cap() {
+        use crate::note_media::files::{MAX_IMAGE_SIZE, MAX_PDF_INPUT_SIZE};
+        use crate::note_media::pdf::tests::{padded_pdf, PAGE_ONE};
+        use crate::note_media::tests::PNG;
+        let f = Fixture::new();
+        let large_pdf = padded_pdf(&[PAGE_ONE], MAX_IMAGE_SIZE as usize + 1);
+
+        let image = attach(&f, "scan.pdf", "application/pdf", &large_pdf).unwrap();
+        assert_eq!(image.mime_type, "application/pdf");
+        assert_eq!(image.size_bytes, large_pdf.len() as i64);
+
+        let path = f.dir.path().join("dropped.pdf");
+        std::fs::write(&path, &large_pdf).unwrap();
+        let image = create_image_impl(
+            f.store.clone(),
+            Some(f.branch.id.clone()),
+            f.project.id.clone(),
+            path.to_string_lossy().into_owned(),
+            None,
+        )
+        .unwrap();
+        assert_eq!(
+            (image.mime_type.as_str(), image.filename.as_str()),
+            ("application/pdf", "dropped.pdf")
+        );
+
+        // Over the PDF cap: refused before decoding (base64) or reading (path).
+        let mut oversized = "JVBERi0x".to_owned(); // "%PDF-1" — a PDF signature
+        oversized.push_str(&"A".repeat((MAX_PDF_INPUT_SIZE.div_ceil(3) * 4) as usize));
+        let err = create_image_from_data_impl(
+            f.store.clone(),
+            None,
+            f.project.id.clone(),
+            "huge.pdf".into(),
+            "application/pdf".into(),
+            oversized,
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err, "PDF exceeds 50 MB limit");
+        let sparse = f.dir.path().join("huge.pdf");
+        let mut file = std::fs::File::create(&sparse).unwrap();
+        std::io::Write::write_all(&mut file, b"%PDF-1.4\n").unwrap();
+        file.set_len(MAX_PDF_INPUT_SIZE + 1).unwrap();
+        let err = create_image_impl(
+            f.store.clone(),
+            None,
+            f.project.id.clone(),
+            sparse.to_string_lossy().into_owned(),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err, "PDF exceeds 50 MB limit");
+
+        // An image over its own cap is still refused with the image message,
+        // on both routes, and from metadata alone on the path route.
+        let mut png = PNG.to_vec();
+        png.resize(MAX_IMAGE_SIZE as usize + 1, 0);
+        let err = attach(&f, "big.png", "image/png", &png).unwrap_err();
+        assert_eq!(err, "media exceeds 10 MB limit");
+        let sparse = f.dir.path().join("big.png");
+        let mut file = std::fs::File::create(&sparse).unwrap();
+        std::io::Write::write_all(&mut file, PNG).unwrap();
+        file.set_len(MAX_IMAGE_SIZE + 1).unwrap();
+        let err = create_image_impl(
+            f.store.clone(),
+            None,
+            f.project.id.clone(),
+            sparse.to_string_lossy().into_owned(),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err, "media exceeds 10 MB limit");
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn malformed_pdf_is_rejected_without_hanging() {
+        let f = Fixture::new();
+        let err = attach(&f, "doc.pdf", "application/pdf", b"%PDF-1.4\ngarbage").unwrap_err();
+        assert!(err.contains("PDF"), "{err}");
+    }
+
+    /// Without CoreGraphics only the signature is checked, so the file is
+    /// still stored and viewable as a PDF.
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn pdf_attachments_are_stored_without_a_renderer() {
+        let f = Fixture::new();
+        let image = attach(&f, "doc.pdf", "application/pdf", b"%PDF-1.4\ngarbage").unwrap();
+        assert_eq!(image.mime_type, "application/pdf");
+    }
 }
diff --git a/apps/staged/src-tauri/src/image_commands/thumbnail.rs b/apps/staged/src-tauri/src/image_commands/thumbnail.rs
new file mode 100644
index 000000000..c7a85228d
--- /dev/null
+++ b/apps/staged/src-tauri/src/image_commands/thumbnail.rs
@@ -0,0 +1,228 @@
+//! Small previews for chat attachments. Images are their own preview; a PDF
+//! has its first page rendered once and cached beside the file.
+
+use crate::note_media::pdf;
+use crate::store::Store;
+use base64::Engine;
+use serde::Serialize;
+
+/// Long edge of a cached PDF thumbnail. The composer and chat history show
+/// attachments at 48–200 CSS px, so this covers a 2x display with room to
+/// spare while staying a few tens of KB.
+pub(crate) const THUMBNAIL_EDGE_PX: u32 = 512;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AttachmentThumbnail {
+    /// PNG (or the image's own) data URL, or `None` when a PDF could not be
+    /// rendered — the frontend shows a document icon instead.
+    pub data_url: Option<String>,
+    /// The attachment's stored MIME, so a PDF can be badged as one.
+    pub mime_type: String,
+    pub filename: String,
+}
+
+pub(crate) fn attachment_thumbnail_impl(
+    store: &Store,
+    image_id: &str,
+) -> Result<AttachmentThumbnail, String> {
+    let image = store
+        .get_image(image_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("Image not found: {image_id}"))?;
+    let path =
+        crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)?;
+    let engine = base64::engine::general_purpose::STANDARD;
+    let data_url = if image.mime_type == "application/pdf" {
+        pdf_thumbnail_png(&image.project_id, &image.id, &path)
+            .map(|png| format!("data:image/png;base64,{}", engine.encode(png)))
+    } else {
+        let bytes = std::fs::read(&path).map_err(|e| format!("Failed to read image: {e}"))?;
+        Some(format!(
+            "data:{};base64,{}",
+            image.mime_type,
+            engine.encode(bytes)
+        ))
+    };
+    Ok(AttachmentThumbnail {
+        data_url,
+        mime_type: image.mime_type,
+        filename: image.filename,
+    })
+}
+
+/// The cached first-page PNG, rendering and caching it on first use. `None`
+/// when the page cannot be rendered (no renderer on this platform, or a PDF
+/// CoreGraphics opens but cannot draw); a thumbnail is not worth failing the
+/// attachment over, and the cache is never written for a failed render so a
+/// later attempt can succeed.
+fn pdf_thumbnail_png(
+    project_id: &str,
+    image_id: &str,
+    pdf_path: &std::path::Path,
+) -> Option<Vec<u8>> {
+    let cache = crate::store::images::thumbnail_file_path(project_id, image_id).ok()?;
+    if let Ok(png) = std::fs::read(&cache) {
+        if png.starts_with(b"\x89PNG\r\n\x1a\n") {
+            return Some(png);
+        }
+    }
+    let bytes = std::fs::read(pdf_path)
+        .map_err(|e| log::warn!("Cannot read PDF attachment {image_id}: {e}"))
+        .ok()?;
+    let rendered = pdf::render_first_page(&bytes, THUMBNAIL_EDGE_PX)
+        .map_err(|e| log::warn!("Cannot render thumbnail for PDF attachment {image_id}: {e}"))
+        .ok()?;
+    match crate::store::images::thumbnail_temp_file_path(project_id, image_id) {
+        Ok(temp) => {
+            if let Err(e) = cache_thumbnail(&cache, &temp, &rendered.png) {
+                log::warn!("Cannot cache thumbnail {}: {e}", cache.display());
+            }
+        }
+        Err(e) => log::warn!("Cannot cache thumbnail {}: {e}", cache.display()),
+    }
+    Some(rendered.png)
+}
+
+/// Write the PNG beside the cache and rename it into place, so a concurrent
+/// reader (the composer strip and the history effect ask for a new
+/// attachment at the same moment) sees either no cache or a complete file,
+/// never a partial one that passes the signature check. The temp file does
+/// not outlive a failure.
+fn cache_thumbnail(
+    cache: &std::path::Path,
+    temp: &std::path::Path,
+    png: &[u8],
+) -> std::io::Result<()> {
+    let result = std::fs::write(temp, png).and_then(|()| std::fs::rename(temp, cache));
+    if result.is_err() {
+        let _ = std::fs::remove_file(temp);
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::note_media::files::store_sniffed_image;
+    use crate::note_media::pdf::tests::{tiny_pdf, PAGE_ONE};
+    use crate::note_media::tests::{Fixture, PNG};
+
+    fn stored_pdf(f: &Fixture) -> crate::store::Image {
+        store_sniffed_image(
+            &f.store,
+            Some(&f.branch.id),
+            &f.project.id,
+            None,
+            "doc.pdf",
+            &tiny_pdf(&[PAGE_ONE]),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn images_are_their_own_thumbnail() {
+        let f = Fixture::new();
+        let image =
+            store_sniffed_image(&f.store, None, &f.project.id, None, "shot.png", PNG).unwrap();
+        let thumbnail = attachment_thumbnail_impl(&f.store, &image.id).unwrap();
+        assert_eq!(
+            thumbnail,
+            AttachmentThumbnail {
+                data_url: Some(format!(
+                    "data:image/png;base64,{}",
+                    base64::engine::general_purpose::STANDARD.encode(PNG)
+                )),
+                mime_type: "image/png".into(),
+                filename: "shot.png".into(),
+            }
+        );
+        assert!(
+            crate::store::images::thumbnail_file_path(&f.project.id, &image.id)
+                .map(|p| !p.exists())
+                .unwrap_or(true)
+        );
+
+        let err = attachment_thumbnail_impl(&f.store, "missing").unwrap_err();
+        assert!(err.contains("not found"), "{err}");
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn pdf_thumbnails_are_rendered_once_and_cached_beside_the_pdf() {
+        let f = Fixture::new();
+        let image = stored_pdf(&f);
+        let thumbnail = attachment_thumbnail_impl(&f.store, &image.id).unwrap();
+        assert_eq!(thumbnail.mime_type, "application/pdf");
+        assert_eq!(thumbnail.filename, "doc.pdf");
+        let data_url = thumbnail.data_url.unwrap();
+        let png = base64::engine::general_purpose::STANDARD
+            .decode(data_url.strip_prefix("data:image/png;base64,").unwrap())
+            .unwrap();
+        let pixmap = tiny_skia::Pixmap::decode_png(&png).unwrap();
+        // Letter page at a 512 px long edge.
+        assert_eq!((pixmap.width(), pixmap.height()), (396, 512));
+        assert!(pixmap.pixels().iter().any(|p| p.red() < 128));
+
+        let cache = crate::store::images::thumbnail_file_path(&f.project.id, &image.id).unwrap();
+        assert_eq!(std::fs::read(&cache).unwrap(), png);
+
+        // The cache is what is served from now on, even once the PDF is gone.
+        std::fs::remove_file(
+            crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)
+                .unwrap(),
+        )
+        .unwrap();
+        assert_eq!(
+            attachment_thumbnail_impl(&f.store, &image.id)
+                .unwrap()
+                .data_url,
+            Some(data_url)
+        );
+
+        // Rendering left no temp file behind.
+        assert_eq!(thumbnail_temp_files(&cache), Vec::<String>::new());
+
+        // Deleting the attachment removes the thumbnail with it, and any
+        // temp file a crash mid-write left behind.
+        let stray = cache.with_file_name(format!("{}.thumb.1-0.tmp", image.id));
+        std::fs::write(&stray, b"partial").unwrap();
+        crate::note_media::files::delete_media_file(&f.store, &image).unwrap();
+        assert!(!cache.exists());
+        assert!(!stray.exists());
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn a_failed_cache_write_serves_the_render_and_leaves_no_temp_file() {
+        let f = Fixture::new();
+        let image = stored_pdf(&f);
+        let cache = crate::store::images::thumbnail_file_path(&f.project.id, &image.id).unwrap();
+        // A directory where the cache file goes: the rename cannot land.
+        std::fs::create_dir(&cache).unwrap();
+        let thumbnail = attachment_thumbnail_impl(&f.store, &image.id).unwrap();
+        assert!(thumbnail.data_url.is_some());
+        assert!(cache.is_dir());
+        assert_eq!(thumbnail_temp_files(&cache), Vec::<String>::new());
+    }
+
+    /// Names of thumbnail temp files beside `cache`.
+    fn thumbnail_temp_files(cache: &std::path::Path) -> Vec<String> {
+        std::fs::read_dir(cache.parent().unwrap())
+            .unwrap()
+            .flatten()
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|n| n.contains(".thumb.") && n.ends_with(".tmp"))
+            .collect()
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn pdf_thumbnails_are_absent_without_a_renderer() {
+        let f = Fixture::new();
+        let image = stored_pdf(&f);
+        let thumbnail = attachment_thumbnail_impl(&f.store, &image.id).unwrap();
+        assert_eq!(thumbnail.data_url, None);
+        assert_eq!(thumbnail.mime_type, "application/pdf");
+    }
+}
diff --git a/apps/staged/src-tauri/src/image_commands/tool_results.rs b/apps/staged/src-tauri/src/image_commands/tool_results.rs
index debc7e63d..2fbf439ba 100644
--- a/apps/staged/src-tauri/src/image_commands/tool_results.rs
+++ b/apps/staged/src-tauri/src/image_commands/tool_results.rs
@@ -1,4 +1,4 @@
-use crate::note_media::files::{mime_for_extension, MAX_IMAGE_SIZE};
+use crate::note_media::files::{mime_for_extension, size_error, MAX_IMAGE_SIZE};
 const ALLOWED_IMAGE_EXTENSIONS: &[&str] = &["png", "jpg", "jpeg", "gif", "webp"];
 use base64::Engine;
 use std::io::Read;
@@ -27,14 +27,14 @@ pub fn read_image_file(file_path: String) -> Result<String, String> {
         return Err("Image path is not a file".to_string());
     }
     if metadata.len() > MAX_IMAGE_SIZE {
-        return Err("Image too large (max 10 MB)".to_string());
+        return Err(size_error("Image", MAX_IMAGE_SIZE));
     }
     let mut bytes = Vec::new();
     file.take(MAX_IMAGE_SIZE + 1)
         .read_to_end(&mut bytes)
         .map_err(|e| format!("Failed to read image: {e}"))?;
     if bytes.len() as u64 > MAX_IMAGE_SIZE {
-        return Err("Image too large (max 10 MB)".to_string());
+        return Err(size_error("Image", MAX_IMAGE_SIZE));
     }
     Ok(format!(
         "data:{};base64,{}",
@@ -87,6 +87,6 @@ mod tests {
             .unwrap();
         assert!(read_image_file(path.to_string_lossy().into_owned())
             .unwrap_err()
-            .contains("too large"));
+            .contains("exceeds 10 MB limit"));
     }
 }
diff --git a/apps/staged/src-tauri/src/lib.rs b/apps/staged/src-tauri/src/lib.rs
index 64aa53c14..8ab5ff0ac 100644
--- a/apps/staged/src-tauri/src/lib.rs
+++ b/apps/staged/src-tauri/src/lib.rs
@@ -2398,6 +2398,7 @@ pub fn run() {
             image_commands::delete_image,
             image_commands::list_branch_images,
             image_commands::create_image_from_data,
+            image_commands::get_attachment_thumbnail,
             // Timeline delete commands
             timeline::get_worktree_changes_preview,
             timeline::discard_worktree_changes,
diff --git a/apps/staged/src-tauri/src/note_media/files.rs b/apps/staged/src-tauri/src/note_media/files.rs
index dfffbc57b..37e3cc8cf 100644
--- a/apps/staged/src-tauri/src/note_media/files.rs
+++ b/apps/staged/src-tauri/src/note_media/files.rs
@@ -6,7 +6,25 @@ use std::io::Read;
 use std::path::Path;
 
 pub(crate) const MAX_IMAGE_SIZE: u64 = 10 * 1024 * 1024;
+/// PDF attachments (scans and print-ready files routinely run 10–50 MB) get
+/// their own cap; they are stored as-is, and only the PNGs rendered from them
+/// for thumbnails and the agent prompt have to satisfy [`MAX_IMAGE_SIZE`].
+pub(crate) const MAX_PDF_INPUT_SIZE: u64 = 50 * 1024 * 1024;
 pub(crate) const MAX_VIDEO_SIZE: u64 = 100 * 1024 * 1024;
+
+pub(crate) fn size_error(what: &str, cap: u64) -> String {
+    format!("{what} exceeds {} MB limit", cap / 1024 / 1024)
+}
+
+/// Input cap for a chat attachment, decided from its leading bytes, with the
+/// noun its size error names so an oversized PDF is reported as such.
+pub(crate) fn attachment_limit(header: &[u8]) -> (u64, &'static str) {
+    if super::pdf::is_pdf(header) {
+        (MAX_PDF_INPUT_SIZE, "PDF")
+    } else {
+        (MAX_IMAGE_SIZE, "media")
+    }
+}
 pub(crate) const MAX_REMOTE_VIDEO_SIZE: i64 = 20 * 1024 * 1024;
 
 pub(crate) fn extension(filename: &str) -> String {
@@ -26,13 +44,20 @@ pub(crate) fn mime_for_extension(ext: &str) -> Option<&'static str> {
         "mp4" => "video/mp4",
         "webm" => "video/webm",
         "mov" => "video/quicktime",
+        "pdf" => "application/pdf",
         _ => return None,
     })
 }
 
+/// Cap for a note media reference. PDFs are chat attachments only: the note
+/// renderer has no PDF figure, so a `.pdf` reference is refused here rather
+/// than stored and shown broken.
 pub(crate) fn size_limit(filename: &str, allow_video: bool) -> Result<u64, String> {
     let ext = extension(filename);
     let mime = mime_for_extension(&ext).ok_or("unsupported media format")?;
+    if mime == "application/pdf" {
+        return Err("PDFs cannot be embedded in notes".into());
+    }
     if mime.starts_with("video/") {
         if !allow_video {
             return Err("only images can be uploaded here".into());
@@ -47,6 +72,8 @@ pub(crate) fn size_limit(filename: &str, allow_video: bool) -> Result<u64, Strin
 pub(crate) fn sniff_format(bytes: &[u8]) -> Option<&'static str> {
     if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
         Some("png")
+    } else if super::pdf::is_pdf(bytes) {
+        Some("pdf")
     } else if bytes.starts_with(b"\xff\xd8\xff") {
         Some("jpg")
     } else if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
@@ -79,7 +106,7 @@ pub(crate) fn validate_media(
 ) -> Result<&'static str, String> {
     let cap = size_limit(filename, allow_video)?;
     if bytes.len() as u64 > cap {
-        return Err(format!("media exceeds {} MB limit", cap / 1024 / 1024));
+        return Err(size_error("media", cap));
     }
     let ext = extension(filename);
     let valid = match (ext.as_str(), sniff_format(bytes)) {
@@ -107,17 +134,24 @@ pub(crate) fn store_sniffed_image(
     filename: &str,
     bytes: &[u8],
 ) -> Result<Image, String> {
-    if bytes.len() as u64 > MAX_IMAGE_SIZE {
-        return Err(format!(
-            "media exceeds {} MB limit",
-            MAX_IMAGE_SIZE / 1024 / 1024
-        ));
+    let (cap, what) = attachment_limit(bytes);
+    if bytes.len() as u64 > cap {
+        return Err(size_error(what, cap));
+    }
+    // A PDF is stored byte-for-byte so the viewer can show the vector
+    // original; thumbnails and the agent prompt render pages from it later.
+    // Only this chat/timeline path accepts one: note ingest (`validate_media`)
+    // still refuses `.pdf` references.
+    if super::pdf::is_pdf(bytes) {
+        super::pdf::check(bytes)?;
     }
     let sniffed = sniff_format(bytes).ok_or("unsupported image format")?;
-    if mime_for_extension(sniffed).unwrap().starts_with("video/") {
+    // Every sniffed extension has a MIME entry.
+    let mime = mime_for_extension(sniffed).unwrap();
+    if mime.starts_with("video/") {
         return Err("only images can be uploaded here".into());
     }
-    let filename = if mime_for_extension(&extension(filename)) == mime_for_extension(sniffed) {
+    let filename = if mime_for_extension(&extension(filename)) == Some(mime) {
         filename.to_owned()
     } else {
         Path::new(filename)
@@ -125,8 +159,10 @@ pub(crate) fn store_sniffed_image(
             .to_string_lossy()
             .into_owned()
     };
-    store_media_file(
-        store, branch_id, project_id, session_id, &filename, bytes, false,
+    // Already validated above (cap, signature, no video); `validate_media`
+    // would refuse the PDF a note cannot embed.
+    write_media(
+        store, branch_id, project_id, session_id, &filename, mime, bytes,
     )
 }
 
@@ -161,6 +197,35 @@ impl From<&str> for ReadError {
 }
 
 pub(crate) fn read_local(path: &Path, cap: u64) -> Result<Vec<u8>, ReadError> {
+    let (file, len) = open_regular(path)?;
+    if len > cap {
+        return Err(size_error("media", cap).into());
+    }
+    read_capped(file, Vec::new(), cap)
+}
+
+/// [`read_local`] for a chat attachment, whose cap depends on what the file
+/// is (see [`attachment_limit`]). The signature is read before the body so an
+/// oversized image is still refused from its metadata, without buffering
+/// anything like [`MAX_PDF_INPUT_SIZE`] first.
+pub(crate) fn read_local_attachment(path: &Path) -> Result<Vec<u8>, ReadError> {
+    let (mut file, len) = open_regular(path)?;
+    let mut bytes = Vec::new();
+    (&mut file)
+        .take(PDF_SIGNATURE_LEN)
+        .read_to_end(&mut bytes)
+        .map_err(|_| "cannot read media file")?;
+    let (cap, what) = attachment_limit(&bytes);
+    if len > cap {
+        return Err(size_error(what, cap).into());
+    }
+    read_capped(file, bytes, cap)
+}
+
+const PDF_SIGNATURE_LEN: u64 = b"%PDF-".len() as u64;
+
+/// Open a regular file for reading and return it with its current length.
+fn open_regular(path: &Path) -> Result<(std::fs::File, u64), ReadError> {
     let mut options = std::fs::OpenOptions::new();
     options.read(true);
     #[cfg(unix)]
@@ -177,11 +242,13 @@ pub(crate) fn read_local(path: &Path, cap: u64) -> Result<Vec<u8>, ReadError> {
     if !metadata.is_file() {
         return Err("media must be a regular file".into());
     }
-    if metadata.len() > cap {
-        return Err(format!("media exceeds {} MB limit", cap / 1024 / 1024).into());
-    }
-    let mut bytes = Vec::new();
-    file.take(cap + 1)
+    Ok((file, metadata.len()))
+}
+
+/// Read the rest of `file` after `bytes` (already read from it), refusing a
+/// file that grew past `cap` since its metadata was checked.
+fn read_capped(file: std::fs::File, mut bytes: Vec<u8>, cap: u64) -> Result<Vec<u8>, ReadError> {
+    file.take(cap + 1 - bytes.len() as u64)
         .read_to_end(&mut bytes)
         .map_err(|_| "cannot read media file")?;
     if bytes.len() as u64 > cap {
@@ -202,6 +269,22 @@ pub(crate) fn store_media_file(
     allow_video: bool,
 ) -> Result<Image, String> {
     let mime = validate_media(filename, bytes, allow_video)?;
+    write_media(
+        store, branch_id, project_id, session_id, filename, mime, bytes,
+    )
+}
+
+/// Write validated bytes under their MIME: a unique filename on the branch,
+/// the file, then the row (the file is removed if the insert fails).
+fn write_media(
+    store: &Store,
+    branch_id: Option<&str>,
+    project_id: &str,
+    session_id: Option<&str>,
+    filename: &str,
+    mime: &str,
+    bytes: &[u8],
+) -> Result<Image, String> {
     let filename = Path::new(filename)
         .file_name()
         .and_then(|s| s.to_str())
@@ -238,15 +321,7 @@ pub(crate) fn store_media_file(
 
 pub(crate) fn delete_media_file(store: &Store, image: &Image) -> Result<(), String> {
     store.delete_image(&image.id).map_err(|e| e.to_string())?;
-    if let Ok(path) =
-        crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)
-    {
-        if let Err(e) = std::fs::remove_file(&path) {
-            if e.kind() != std::io::ErrorKind::NotFound {
-                log::warn!("Cannot remove media {}: {e}", image.id);
-            }
-        }
-    }
+    crate::store::images::remove_image_files(&image.project_id, &image.id, &image.filename);
     Ok(())
 }
 
@@ -292,7 +367,7 @@ pub(crate) fn read_candidate(
         }
         let bytes = output.stdout;
         if bytes.len() as u64 > cap {
-            return Err(format!("media exceeds {} MB limit", cap / 1024 / 1024).into());
+            return Err(size_error("media", cap).into());
         }
         Ok(bytes)
     } else {
diff --git a/apps/staged/src-tauri/src/note_media/mod.rs b/apps/staged/src-tauri/src/note_media/mod.rs
index 83d9b2915..b1530ed13 100644
--- a/apps/staged/src-tauri/src/note_media/mod.rs
+++ b/apps/staged/src-tauri/src/note_media/mod.rs
@@ -5,6 +5,7 @@ mod blocks;
 pub(crate) mod files;
 mod materialize;
 pub(crate) use materialize::materialize_note_media;
+pub(crate) mod pdf;
 #[cfg(test)]
 pub(crate) use materialize::{materialize_note_media_with, RemoteMedia};
 pub(crate) mod refs;
diff --git a/apps/staged/src-tauri/src/note_media/pdf.rs b/apps/staged/src-tauri/src/note_media/pdf.rs
new file mode 100644
index 000000000..39e545a29
--- /dev/null
+++ b/apps/staged/src-tauri/src/note_media/pdf.rs
@@ -0,0 +1,701 @@
+//! PDF attachments are stored as the PDF itself; this module rasterizes pages
+//! to opaque bitmaps where one is needed: the thumbnail shown next to image
+//! attachments, and the agent prompt, whose transports accept only image
+//! blocks. Rendering uses CoreGraphics in-process (no subprocess, no temp
+//! files, malformed input fails fast instead of hanging). Pages are PNG, or
+//! JPEG when a caller allows it and the PNG cannot meet its size cap.
+//!
+//! macOS only — the shipped target. Other platforms compile stubs so the
+//! Linux CI build stays green; they accept any `%PDF-` payload at store time
+//! and report that rendering needs macOS. The stubs leave the shared types
+//! only half used there, hence the module-wide allowance.
+#![cfg_attr(not(target_os = "macos"), allow(dead_code))]
+
+#[cfg(target_os = "macos")]
+use super::files::size_error;
+use super::files::MAX_IMAGE_SIZE;
+
+/// Long edge of a page rendered for the agent prompt, in pixels. The Claude
+/// API rejects any image over 2000 px on a side once a request carries more
+/// than 20 image blocks (it counts the images resent from earlier turns and
+/// those in tool results, so a 20-page PDF plus one screenshot gets there),
+/// and the high-resolution tier tops out at 2576 px, so 2000 loses nothing a
+/// 2048 would have kept. A letter page lands at ~182 DPI, which keeps body
+/// text legible to a vision model without approaching the attachment size cap.
+pub(crate) const MAX_EDGE_PX: u32 = 2000;
+
+/// Pages are never blown up beyond 4 px per PDF point, so a tiny page does
+/// not become a huge blurry bitmap just to reach the long-edge target.
+#[cfg(target_os = "macos")]
+const MAX_SCALE: f64 = 4.0;
+
+/// Quality of the JPEG a page falls back to when its PNG is over the cap even
+/// at half scale — photographic scans, where a PNG is several times the size
+/// of a JPEG that looks the same.
+#[cfg(target_os = "macos")]
+const JPEG_QUALITY: u8 = 85;
+
+pub(crate) fn is_pdf(bytes: &[u8]) -> bool {
+    bytes.starts_with(b"%PDF-")
+}
+
+pub(crate) struct RenderedPage {
+    pub png: Vec<u8>,
+    /// Pages in the document, so callers can say "page 1 of N".
+    pub page_count: usize,
+}
+
+impl std::fmt::Debug for RenderedPage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RenderedPage")
+            .field("png_bytes", &self.png.len())
+            .field("page_count", &self.page_count)
+            .finish()
+    }
+}
+
+/// One page, encoded: PNG unless the [`Fit`] allowed a JPEG and it was needed.
+pub(crate) struct EncodedPage {
+    pub bytes: Vec<u8>,
+    pub mime_type: &'static str,
+}
+
+impl std::fmt::Debug for EncodedPage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EncodedPage")
+            .field("bytes", &self.bytes.len())
+            .field("mime_type", &self.mime_type)
+            .finish()
+    }
+}
+
+/// How large an encoded page may be, and how far to go to get it there.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Fit {
+    /// Ceiling on the encoded bytes.
+    pub max_bytes: u64,
+    /// When the PNG is over the ceiling even at half scale, try a full-scale
+    /// JPEG before giving up on the page.
+    pub jpeg_fallback: bool,
+}
+
+impl Fit {
+    /// A PNG under the media cap: thumbnails, which are cached as PNG files.
+    pub(crate) const PNG_MEDIA: Fit = Fit {
+        max_bytes: MAX_IMAGE_SIZE,
+        jpeg_fallback: false,
+    };
+}
+
+/// Render page 1 to a white-backed PNG whose long edge is `max_edge_px`
+/// (less when that would exceed [`MAX_SCALE`]).
+pub(crate) fn render_first_page(bytes: &[u8], max_edge_px: u32) -> Result<RenderedPage, String> {
+    let document = Document::open(bytes)?;
+    let page = document.render_page(1, max_edge_px, Fit::PNG_MEDIA)?;
+    Ok(RenderedPage {
+        png: page.bytes,
+        page_count: document.page_count(),
+    })
+}
+
+/// Reject what CoreGraphics cannot open before it is stored, so a `%PDF-`
+/// prefix on garbage never becomes an attachment that fails to render later.
+#[cfg(target_os = "macos")]
+pub(crate) fn check(bytes: &[u8]) -> Result<(), String> {
+    Document::open(bytes).map(drop)
+}
+
+/// An open PDF. Pages are rendered one at a time so a caller with a page cap
+/// or a byte budget can stop without rasterizing the rest.
+#[cfg(target_os = "macos")]
+pub(crate) struct Document {
+    document: objc2_core_foundation::CFRetained<objc2_core_graphics::CGPDFDocument>,
+    page_count: usize,
+}
+
+#[cfg(target_os = "macos")]
+impl Document {
+    pub(crate) fn open(bytes: &[u8]) -> Result<Self, String> {
+        use objc2_core_foundation::CFData;
+        use objc2_core_graphics::{CGDataProvider, CGPDFDocument};
+
+        let data = CFData::from_bytes(bytes);
+        let provider =
+            CGDataProvider::with_cf_data(Some(&data)).ok_or("could not read PDF data")?;
+        // CoreGraphics returns no document for anything it cannot parse, so a
+        // `%PDF-` prefix on garbage is rejected here rather than drawn as blank.
+        let document = CGPDFDocument::with_provider(Some(&provider)).ok_or("could not open PDF")?;
+        let page_count = CGPDFDocument::number_of_pages(Some(&document));
+        if page_count == 0 {
+            return Err("PDF has no pages".into());
+        }
+        Ok(Document {
+            document,
+            page_count,
+        })
+    }
+
+    pub(crate) fn page_count(&self) -> usize {
+        self.page_count
+    }
+
+    /// Draw page `number` (1-based) at `max_edge_px` along its long edge
+    /// (less when that would exceed [`MAX_SCALE`]) and encode it within
+    /// `fit`: see [`fit_page`].
+    pub(crate) fn render_page(
+        &self,
+        number: usize,
+        max_edge_px: u32,
+        fit: Fit,
+    ) -> Result<EncodedPage, String> {
+        use objc2_core_graphics::{CGPDFBox, CGPDFDocument, CGPDFPage};
+
+        let page = CGPDFDocument::page(Some(&self.document), number)
+            .ok_or_else(|| format!("could not read PDF page {number}"))?;
+
+        // CropBox is what Preview and Quick Look display (CoreGraphics clips
+        // it to the MediaBox, and returns the MediaBox when none is set), so
+        // a print-ready PDF renders without its bleed and crop marks. Fall
+        // back to the MediaBox only when the CropBox is unusable.
+        let mut page_box = CGPDFBox::CropBox;
+        let mut rect = CGPDFPage::box_rect(Some(&page), page_box);
+        if !is_drawable(rect.size.width, rect.size.height) {
+            page_box = CGPDFBox::MediaBox;
+            rect = CGPDFPage::box_rect(Some(&page), page_box);
+            if !is_drawable(rect.size.width, rect.size.height) {
+                return Err("PDF page has no drawable area".into());
+            }
+        }
+        // `drawing_transform` honours the page's own /Rotate, so the bitmap
+        // must take the rotated orientation for the page to fill it.
+        let rotated = CGPDFPage::rotation_angle(Some(&page)).rem_euclid(180) == 90;
+        let (w_pt, h_pt) = if rotated {
+            (rect.size.height, rect.size.width)
+        } else {
+            (rect.size.width, rect.size.height)
+        };
+        let scale = (f64::from(max_edge_px) / w_pt.max(h_pt)).min(MAX_SCALE);
+        fit_page(
+            |scale| render(&page, page_box, (w_pt, h_pt), scale),
+            scale,
+            fit,
+        )
+    }
+}
+
+/// Encode the page `render` draws at `scale` px/pt within `fit.max_bytes`:
+/// as a PNG; if that is over, as a PNG of a render at half scale; if that is
+/// still over and `fit` allows it, as a JPEG of the full-scale render; else
+/// fail with the size message.
+#[cfg(target_os = "macos")]
+fn fit_page(
+    render: impl Fn(f64) -> Result<tiny_skia::Pixmap, String>,
+    scale: f64,
+    fit: Fit,
+) -> Result<EncodedPage, String> {
+    let fits = |bytes: &[u8]| bytes.len() as u64 <= fit.max_bytes;
+    let full = render(scale)?;
+    let png = encode_png(&full)?;
+    if fits(&png) {
+        return Ok(EncodedPage::png(png));
+    }
+    let png = encode_png(&render(scale / 2.0)?)?;
+    if fits(&png) {
+        return Ok(EncodedPage::png(png));
+    }
+    if fit.jpeg_fallback {
+        let jpeg = encode_jpeg(&full)?;
+        if fits(&jpeg) {
+            return Ok(EncodedPage {
+                bytes: jpeg,
+                mime_type: "image/jpeg",
+            });
+        }
+    }
+    Err(size_error("PDF page", fit.max_bytes))
+}
+
+#[cfg(target_os = "macos")]
+impl EncodedPage {
+    fn png(bytes: Vec<u8>) -> Self {
+        EncodedPage {
+            bytes,
+            mime_type: "image/png",
+        }
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn encode_png(pixmap: &tiny_skia::Pixmap) -> Result<Vec<u8>, String> {
+    pixmap
+        .encode_png()
+        .map_err(|e| format!("could not encode PDF page: {e}"))
+}
+
+/// Pages are drawn over opaque white, so demultiplying changes nothing today;
+/// it keeps the conversion right should the background ever go.
+#[cfg(target_os = "macos")]
+fn encode_jpeg(pixmap: &tiny_skia::Pixmap) -> Result<Vec<u8>, String> {
+    use image::ImageEncoder;
+
+    let rgb: Vec<u8> = pixmap
+        .pixels()
+        .iter()
+        .flat_map(|p| {
+            let c = p.demultiply();
+            [c.red(), c.green(), c.blue()]
+        })
+        .collect();
+    let mut out = Vec::new();
+    image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, JPEG_QUALITY)
+        .write_image(
+            &rgb,
+            pixmap.width(),
+            pixmap.height(),
+            image::ExtendedColorType::Rgb8,
+        )
+        .map_err(|e| format!("could not encode PDF page as JPEG: {e}"))?;
+    Ok(out)
+}
+
+#[cfg(target_os = "macos")]
+fn is_drawable(width: f64, height: f64) -> bool {
+    width.is_finite() && height.is_finite() && width >= 1.0 && height >= 1.0
+}
+
+#[cfg(target_os = "macos")]
+fn pixel_size(w_pt: f64, h_pt: f64, scale: f64) -> (u32, u32) {
+    let px = |pt: f64| (pt * scale).round().max(1.0) as u32;
+    (px(w_pt), px(h_pt))
+}
+
+/// Draw the page, displayed at `(w_pt, h_pt)` points, into a fresh RGBA
+/// bitmap at `scale` px/pt as a tiny-skia pixmap (premultiplied RGBA8, the
+/// same layout CoreGraphics writes for `PremultipliedLast`).
+#[cfg(target_os = "macos")]
+fn render(
+    page: &objc2_core_graphics::CGPDFPage,
+    page_box: objc2_core_graphics::CGPDFBox,
+    (w_pt, h_pt): (f64, f64),
+    scale: f64,
+) -> Result<tiny_skia::Pixmap, String> {
+    use objc2_core_foundation::{CGPoint, CGRect, CGSize};
+    use objc2_core_graphics::{
+        CGBitmapContextCreate, CGColorSpace, CGContext, CGImageAlphaInfo, CGPDFPage,
+    };
+
+    let (width, height) = pixel_size(w_pt, h_pt, scale);
+    let (w, h) = (width as usize, height as usize);
+    let mut buf = vec![0u8; w * h * 4];
+    let space = CGColorSpace::new_device_rgb().ok_or("could not create color space")?;
+    let bitmap = CGRect {
+        origin: CGPoint { x: 0.0, y: 0.0 },
+        size: CGSize {
+            width: f64::from(width),
+            height: f64::from(height),
+        },
+    };
+    // In points, after the CTM is scaled. `drawing_transform` only ever
+    // scales a page *down* to fit its rect (otherwise it centres the page at
+    // 1:1), so the magnification has to come from the CTM, and the rect is
+    // the page's own displayed size so the box lands flush at the origin.
+    let page_rect = CGRect {
+        origin: CGPoint { x: 0.0, y: 0.0 },
+        size: CGSize {
+            width: w_pt,
+            height: h_pt,
+        },
+    };
+    {
+        // SAFETY: the context draws into `buf`, which outlives it — the
+        // context is released at the end of this block, before `buf` moves
+        // into the pixmap — and the width, height, and row stride describe
+        // exactly the RGBA8 buffer allocated above.
+        let context = unsafe {
+            CGBitmapContextCreate(
+                buf.as_mut_ptr().cast(),
+                w,
+                h,
+                8,
+                w * 4,
+                Some(&space),
+                CGImageAlphaInfo::PremultipliedLast.0,
+            )
+        }
+        .ok_or("could not create bitmap context")?;
+        let ctx = Some(&*context);
+        // White behind the page: PDFs have no background, and a transparent
+        // PNG would lose black text on the dark theme and for the agent.
+        CGContext::set_rgb_fill_color(ctx, 1.0, 1.0, 1.0, 1.0);
+        CGContext::fill_rect(ctx, bitmap);
+        CGContext::scale_ctm(ctx, scale, scale);
+        CGContext::concat_ctm(
+            ctx,
+            CGPDFPage::drawing_transform(Some(page), page_box, page_rect, 0, true),
+        );
+        CGContext::draw_pdf_page(ctx, Some(page));
+    }
+    let size = tiny_skia::IntSize::from_wh(width, height).ok_or("invalid PDF page size")?;
+    tiny_skia::Pixmap::from_vec(buf, size).ok_or_else(|| "invalid PDF page bitmap".into())
+}
+
+#[cfg(not(target_os = "macos"))]
+pub(crate) const UNSUPPORTED: &str = "PDF rendering requires macOS";
+
+/// Without a renderer only the signature is checked; the file is still
+/// stored and viewed as a PDF.
+#[cfg(not(target_os = "macos"))]
+pub(crate) fn check(_bytes: &[u8]) -> Result<(), String> {
+    Ok(())
+}
+
+/// No renderer: [`Document::open`] always fails, so no page is ever rendered.
+#[cfg(not(target_os = "macos"))]
+pub(crate) enum Document {}
+
+#[cfg(not(target_os = "macos"))]
+impl Document {
+    pub(crate) fn open(_bytes: &[u8]) -> Result<Self, String> {
+        Err(UNSUPPORTED.into())
+    }
+
+    pub(crate) fn page_count(&self) -> usize {
+        match *self {}
+    }
+
+    pub(crate) fn render_page(
+        &self,
+        _number: usize,
+        _max_edge_px: u32,
+        _fit: Fit,
+    ) -> Result<EncodedPage, String> {
+        match *self {}
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use super::*;
+
+    /// A minimal PDF with one letter-size page per content stream, using the
+    /// built-in Helvetica. Offsets in the xref table are computed, so the
+    /// output is well-formed rather than relying on reader repair.
+    pub(crate) fn tiny_pdf(pages: &[&str]) -> Vec<u8> {
+        tiny_pdf_with(pages, "[0 0 612 792]", None, None)
+    }
+
+    pub(crate) fn tiny_pdf_with(
+        pages: &[&str],
+        media_box: &str,
+        crop_box: Option<&str>,
+        rotate: Option<u32>,
+    ) -> Vec<u8> {
+        build_pdf(pages, media_box, crop_box, rotate, 0)
+    }
+
+    /// [`tiny_pdf`] grown past `min_len` bytes with comment lines after the
+    /// header, so a large file is still a well-formed, instantly rendered PDF
+    /// (the xref offsets skip the comments) — for exercising the size caps.
+    pub(crate) fn padded_pdf(pages: &[&str], min_len: usize) -> Vec<u8> {
+        let pdf = build_pdf(pages, "[0 0 612 792]", None, None, min_len);
+        assert!(pdf.len() >= min_len);
+        pdf
+    }
+
+    fn build_pdf(
+        pages: &[&str],
+        media_box: &str,
+        crop_box: Option<&str>,
+        rotate: Option<u32>,
+        padding: usize,
+    ) -> Vec<u8> {
+        let font_id = 3 + pages.len() * 2;
+        let mut objects = vec![
+            "<< /Type /Catalog /Pages 2 0 R >>".to_owned(),
+            format!(
+                "<< /Type /Pages /Kids [{}] /Count {} >>",
+                (0..pages.len())
+                    .map(|i| format!("{} 0 R", 3 + i * 2))
+                    .collect::<Vec<_>>()
+                    .join(" "),
+                pages.len()
+            ),
+        ];
+        for (i, content) in pages.iter().enumerate() {
+            let crop_box = crop_box
+                .map(|b| format!(" /CropBox {b}"))
+                .unwrap_or_default();
+            let rotate = rotate.map(|r| format!(" /Rotate {r}")).unwrap_or_default();
+            objects.push(format!(
+                "<< /Type /Page /Parent 2 0 R /MediaBox {media_box}{crop_box}{rotate} \
+                 /Resources << /Font << /F1 {font_id} 0 R >> >> /Contents {} 0 R >>",
+                4 + i * 2
+            ));
+            objects.push(format!(
+                "<< /Length {} >>\nstream\n{content}\nendstream",
+                content.len()
+            ));
+        }
+        objects.push("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>".to_owned());
+
+        let mut out = b"%PDF-1.4\n".to_vec();
+        let comment = format!("%{}\n", "x".repeat(4095));
+        while out.len() < padding {
+            out.extend_from_slice(comment.as_bytes());
+        }
+        let mut offsets = Vec::new();
+        for (i, body) in objects.iter().enumerate() {
+            offsets.push(out.len());
+            out.extend_from_slice(format!("{} 0 obj\n{body}\nendobj\n", i + 1).as_bytes());
+        }
+        let xref = out.len();
+        out.extend_from_slice(
+            format!("xref\n0 {}\n0000000000 65535 f \n", objects.len() + 1).as_bytes(),
+        );
+        for offset in offsets {
+            out.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes());
+        }
+        out.extend_from_slice(
+            format!(
+                "trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n",
+                objects.len() + 1
+            )
+            .as_bytes(),
+        );
+        out
+    }
+
+    pub(crate) const PAGE_ONE: &str =
+        "BT /F1 24 Tf 72 700 Td (PAGE ONE Staged PDF probe) Tj ET\n4 w 72 650 m 540 650 l S";
+
+    /// Page one's text plus a second rule, at y=400 pt, that page one lacks.
+    pub(crate) const PAGE_TWO: &str =
+        "BT /F1 24 Tf 72 700 Td (PAGE TWO should not appear) Tj ET\n4 w 72 400 m 540 400 l S";
+
+    #[test]
+    fn detects_the_pdf_signature_only() {
+        assert!(is_pdf(&tiny_pdf(&[PAGE_ONE])));
+        assert!(is_pdf(b"%PDF-1.7 junk"));
+        assert!(!is_pdf(b"\x89PNG\r\n\x1a\n"));
+        assert!(!is_pdf(b" %PDF-1.4"));
+        assert!(!is_pdf(b""));
+    }
+
+    #[cfg(target_os = "macos")]
+    mod macos {
+        use super::*;
+
+        fn decode(png: &[u8]) -> tiny_skia::Pixmap {
+            assert!(png.starts_with(b"\x89PNG\r\n\x1a\n"));
+            tiny_skia::Pixmap::decode_png(png).unwrap()
+        }
+
+        fn is_opaque_white(pixmap: &tiny_skia::Pixmap, x: u32, y: u32) -> bool {
+            let p = pixmap.pixel(x, y).unwrap();
+            (p.red(), p.green(), p.blue(), p.alpha()) == (255, 255, 255, 255)
+        }
+
+        /// Bitmap row through the middle of a 4 pt rule drawn at `y_pt` on a
+        /// letter page rendered [`MAX_EDGE_PX`] tall.
+        fn letter_rule_row(y_pt: f64) -> u32 {
+            ((792.0 - y_pt) * f64::from(MAX_EDGE_PX) / 792.0) as u32
+        }
+
+        #[test]
+        fn renders_first_page_to_opaque_png_at_the_long_edge() {
+            let rendered =
+                render_first_page(&tiny_pdf(&[PAGE_ONE, PAGE_TWO]), MAX_EDGE_PX).unwrap();
+            assert_eq!(rendered.page_count, 2);
+            let pixmap = decode(&rendered.png);
+            // Letter: 2000 / 792 pt ≈ 2.53x, under the 4x ceiling.
+            assert_eq!((pixmap.width(), pixmap.height()), (1545, 2000));
+            for (x, y) in [(0, 0), (1544, 0), (0, 1999), (1544, 1999)] {
+                assert!(is_opaque_white(&pixmap, x, y), "corner {x},{y}");
+            }
+            // The rule at y=650pt from the bottom is drawn; everything is opaque.
+            let p = pixmap.pixel(800, letter_rule_row(650.0)).unwrap();
+            assert!(p.red() < 128 && p.alpha() == 255, "rule pixel {p:?}");
+            assert!(pixmap.pixels().iter().all(|p| p.alpha() == 255));
+            // Page two's own rule, at y=400pt, is not drawn...
+            assert!(is_opaque_white(&pixmap, 800, letter_rule_row(400.0)));
+            // ...and would have been, had page two been the one rendered.
+            let swapped = decode(
+                &render_first_page(&tiny_pdf(&[PAGE_TWO]), MAX_EDGE_PX)
+                    .unwrap()
+                    .png,
+            );
+            let p = swapped.pixel(800, letter_rule_row(400.0)).unwrap();
+            assert!(
+                p.red() < 128 && p.alpha() == 255,
+                "page-two rule pixel {p:?}"
+            );
+        }
+
+        #[test]
+        fn wide_pages_are_downscaled_and_tiny_pages_capped_at_4x() {
+            // Same box as the onboarding flow chart fixture: 3150×1800 pt.
+            let wide = tiny_pdf_with(&[PAGE_ONE], "[0 0 3150 1800]", None, None);
+            let pixmap = decode(&render_first_page(&wide, MAX_EDGE_PX).unwrap().png);
+            assert_eq!((pixmap.width(), pixmap.height()), (2000, 1143));
+
+            let tiny = tiny_pdf_with(&[PAGE_ONE], "[0 0 100 50]", None, None);
+            let pixmap = decode(&render_first_page(&tiny, MAX_EDGE_PX).unwrap().png);
+            assert_eq!((pixmap.width(), pixmap.height()), (400, 200));
+        }
+
+        #[test]
+        fn rotated_pages_take_their_displayed_orientation() {
+            let landscape = tiny_pdf_with(&[PAGE_ONE], "[0 0 612 792]", None, Some(90));
+            let pixmap = decode(&render_first_page(&landscape, MAX_EDGE_PX).unwrap().png);
+            assert_eq!((pixmap.width(), pixmap.height()), (2000, 1545));
+            assert!(pixmap.pixels().iter().any(|p| p.red() < 128));
+        }
+
+        #[test]
+        fn crop_box_wins_over_media_box() {
+            // Letter MediaBox with bleed trimmed to a 300×400 pt CropBox; the
+            // rule is drawn inside the crop, the page-one text outside it.
+            const INSIDE_CROP: &str = "4 w 100 300 m 400 300 l S";
+            let cropped = tiny_pdf_with(
+                &[&format!("{PAGE_ONE}\n{INSIDE_CROP}")],
+                "[0 0 612 792]",
+                Some("[100 100 400 500]"),
+                None,
+            );
+            let pixmap = decode(&render_first_page(&cropped, MAX_EDGE_PX).unwrap().png);
+            // 2000 / 400 pt would be 5x, so the 4x ceiling applies.
+            assert_eq!((pixmap.width(), pixmap.height()), (1200, 1600));
+            let rule_y = ((500.0 - 300.0) * 4.0) as u32;
+            let p = pixmap.pixel(600, rule_y).unwrap();
+            assert!(p.red() < 128 && p.alpha() == 255, "rule pixel {p:?}");
+            for (x, y) in [(0, 0), (1199, 0), (0, 1599), (1199, 1599)] {
+                assert!(is_opaque_white(&pixmap, x, y), "corner {x},{y}");
+            }
+
+            // An empty CropBox is not drawable, so the MediaBox is used.
+            let degenerate = tiny_pdf_with(&[PAGE_ONE], "[0 0 612 792]", Some("[0 0 0 0]"), None);
+            let pixmap = decode(&render_first_page(&degenerate, MAX_EDGE_PX).unwrap().png);
+            assert_eq!((pixmap.width(), pixmap.height()), (1545, 2000));
+        }
+
+        #[test]
+        fn malformed_pdfs_are_rejected_without_hanging() {
+            for bytes in [
+                &b"%PDF-1.4\nnot really a pdf"[..],
+                b"%PDF-",
+                &tiny_pdf(&[])[..],
+            ] {
+                let err = render_first_page(bytes, MAX_EDGE_PX).unwrap_err();
+                assert!(err.contains("PDF"), "{err}");
+                assert_eq!(check(bytes).unwrap_err(), err);
+            }
+            check(&tiny_pdf(&[PAGE_ONE])).unwrap();
+        }
+
+        #[test]
+        fn documents_render_pages_on_demand() {
+            let document = Document::open(&tiny_pdf(&[PAGE_ONE, PAGE_TWO, PAGE_ONE])).unwrap();
+            assert_eq!(document.page_count(), 3);
+            let row = ((792.0 - 400.0) * 512.0 / 792.0) as u32;
+            let first = document.render_page(1, 512, Fit::PNG_MEDIA).unwrap();
+            let second = document.render_page(2, 512, Fit::PNG_MEDIA).unwrap();
+            assert_eq!(
+                (first.mime_type, second.mime_type),
+                ("image/png", "image/png")
+            );
+            let first = decode(&first.bytes);
+            let second = decode(&second.bytes);
+            assert_eq!((first.width(), first.height()), (396, 512));
+            assert!(is_opaque_white(&first, 200, row));
+            assert!(second.pixel(200, row).unwrap().red() < 128);
+
+            let err = document.render_page(4, 512, Fit::PNG_MEDIA).unwrap_err();
+            assert!(err.contains("page 4"), "{err}");
+        }
+
+        /// `fit_page` only sees what the closure returns, so the chain can be
+        /// pinned with stand-in bitmaps whose encoded sizes are known to
+        /// order as a photographic page's do: PNG at half scale under PNG at
+        /// full scale, and the full-scale JPEG under both.
+        #[test]
+        fn pages_fall_back_to_half_scale_then_jpeg_to_meet_the_cap() {
+            let photo = |scale: f64| Ok(photographic_pixmap((256.0 * scale) as u32));
+            let png_full = encode_png(&photo(1.0).unwrap()).unwrap();
+            let png_half = encode_png(&photo(0.5).unwrap()).unwrap();
+            let jpeg_full = encode_jpeg(&photo(1.0).unwrap()).unwrap();
+            assert!(
+                jpeg_full.len() < png_half.len() && png_half.len() < png_full.len(),
+                "stand-in sizes: png {} / half {} / jpeg {}",
+                png_full.len(),
+                png_half.len(),
+                jpeg_full.len()
+            );
+            let fit = |max_bytes: usize, jpeg_fallback: bool| Fit {
+                max_bytes: max_bytes as u64,
+                jpeg_fallback,
+            };
+
+            let page = fit_page(photo, 1.0, fit(png_full.len(), false)).unwrap();
+            assert_eq!(
+                (page.mime_type, page.bytes.len()),
+                ("image/png", png_full.len())
+            );
+            assert_eq!(decode(&page.bytes).width(), 256);
+
+            let page = fit_page(photo, 1.0, fit(png_full.len() - 1, false)).unwrap();
+            assert_eq!(
+                (page.mime_type, page.bytes.len()),
+                ("image/png", png_half.len())
+            );
+            assert_eq!(decode(&page.bytes).width(), 128);
+
+            let page = fit_page(photo, 1.0, fit(png_half.len() - 1, true)).unwrap();
+            assert_eq!(
+                (page.mime_type, page.bytes.len()),
+                ("image/jpeg", jpeg_full.len())
+            );
+            assert!(page.bytes.starts_with(&[0xFF, 0xD8, 0xFF]));
+
+            let err = fit_page(photo, 1.0, fit(png_half.len() - 1, false)).unwrap_err();
+            assert_eq!(err, "PDF page exceeds 0 MB limit");
+            let err = fit_page(photo, 1.0, fit(jpeg_full.len() - 1, true)).unwrap_err();
+            assert!(err.starts_with("PDF page exceeds"), "{err}");
+        }
+
+        /// Smooth colour gradients under low-amplitude per-pixel noise: PNG
+        /// filters cannot predict the noise, JPEG quantizes it away.
+        fn photographic_pixmap(edge: u32) -> tiny_skia::Pixmap {
+            let mut pixmap = tiny_skia::Pixmap::new(edge, edge).unwrap();
+            let mut seed = 0x2545_F491_4F6C_DD1Du64;
+            let mut noise = move || {
+                seed ^= seed << 13;
+                seed ^= seed >> 7;
+                seed ^= seed << 17;
+                (seed % 7) as f64 - 3.0
+            };
+            let channel = |v: f64| v.clamp(0.0, 255.0) as u8;
+            for (i, pixel) in pixmap.pixels_mut().iter_mut().enumerate() {
+                let x = f64::from(i as u32 % edge) / f64::from(edge);
+                let y = f64::from(i as u32 / edge) / f64::from(edge);
+                let r = channel(x * 200.0 + 30.0 + noise());
+                let g = channel(y * 200.0 + 30.0 + noise());
+                let b = channel(((x + y) * 3.0).sin() * 80.0 + 128.0 + noise());
+                *pixel = tiny_skia::ColorU8::from_rgba(r, g, b, 255).premultiply();
+            }
+            pixmap
+        }
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn reports_platform_support() {
+        let pdf = tiny_pdf(&[PAGE_ONE]);
+        let err = render_first_page(&pdf, MAX_EDGE_PX).unwrap_err();
+        assert!(err.contains("macOS"), "{err}");
+        let err = Document::open(&pdf).err().unwrap();
+        assert!(err.contains("macOS"), "{err}");
+        // Storage only needs the signature here.
+        check(&pdf).unwrap();
+        check(b"%PDF-1.4\ngarbage").unwrap();
+    }
+}
diff --git a/apps/staged/src-tauri/src/note_media/tests.rs b/apps/staged/src-tauri/src/note_media/tests.rs
index 311d6327f..7c671758c 100644
--- a/apps/staged/src-tauri/src/note_media/tests.rs
+++ b/apps/staged/src-tauri/src/note_media/tests.rs
@@ -550,6 +550,19 @@ fn validates_magic_and_caps_by_kind_without_reading_oversized_files() {
     }
     assert!(validate_media("fake.mp4", b"\0\0\0\x18ftypavif\0\0\0\0", true).is_err());
     assert!(validate_media("fake.webm", b"\x1a\x45\xdf\xa3matroska", true).is_err());
+    // PDFs are chat attachments only; note ingest refuses them even though
+    // the sniffer and MIME map know the format (for the attachment store).
+    assert_eq!(sniff_format(b"%PDF-1.7 ..."), Some("pdf"));
+    assert_eq!(mime_for_extension("pdf"), Some("application/pdf"));
+    assert_eq!(
+        validate_media(
+            "a.pdf",
+            &pdf::tests::tiny_pdf(&[pdf::tests::PAGE_ONE]),
+            true
+        ),
+        Err("PDFs cannot be embedded in notes".into())
+    );
+    assert!(size_limit("a.pdf", true).is_err());
     assert!(size_limit("a.mp4", false).is_err());
     assert_eq!(size_limit("a.png", true).unwrap(), MAX_IMAGE_SIZE);
     assert_eq!(size_limit("a.mov", true).unwrap(), MAX_VIDEO_SIZE);
@@ -565,6 +578,55 @@ fn validates_magic_and_caps_by_kind_without_reading_oversized_files() {
     }
 }
 
+#[test]
+fn attachment_reads_pick_their_cap_from_the_file_signature() {
+    let f = Fixture::new();
+    let sparse = |name: &str, header: &[u8], len: u64| {
+        let path = f.dir.path().join(name);
+        let mut file = std::fs::File::create(&path).unwrap();
+        std::io::Write::write_all(&mut file, header).unwrap();
+        file.set_len(len).unwrap();
+        path
+    };
+    // A PDF between the image and PDF caps is read in full.
+    let path = sparse("a.pdf", b"%PDF-1.4\n", files::MAX_IMAGE_SIZE + 1);
+    let bytes = files::read_local_attachment(&path).unwrap();
+    assert_eq!(bytes.len() as u64, files::MAX_IMAGE_SIZE + 1);
+    assert!(bytes.starts_with(b"%PDF-1.4\n"));
+    assert_eq!(
+        files::read_local_attachment(&sparse("b.pdf", b"%PDF-", files::MAX_PDF_INPUT_SIZE + 1)),
+        Err("PDF exceeds 50 MB limit".into())
+    );
+    // Anything else keeps the image cap, judged from metadata.
+    assert_eq!(
+        files::read_local_attachment(&sparse("c.png", PNG, files::MAX_IMAGE_SIZE + 1)),
+        Err("media exceeds 10 MB limit".into())
+    );
+    // Files shorter than the signature are read, not mistaken for PDFs.
+    assert_eq!(
+        files::read_local_attachment(&sparse("d.png", b"%PD", 3)).unwrap(),
+        b"%PD"
+    );
+    assert_eq!(
+        files::read_local_attachment(f.dir.path()),
+        Err("media must be a regular file".into())
+    );
+    assert_eq!(
+        files::read_local_attachment(&f.dir.path().join("missing.pdf")),
+        Err(files::ReadError::NotFound("media file is unavailable"))
+    );
+
+    // The same decision for bytes already in memory.
+    let mut pdf = b"%PDF-1.4\n".to_vec();
+    pdf.resize(files::MAX_PDF_INPUT_SIZE as usize + 1, b' ');
+    let err = files::store_sniffed_image(&f.store, None, &f.project.id, None, "a.pdf", &pdf);
+    assert_eq!(err.unwrap_err(), "PDF exceeds 50 MB limit");
+    let mut png = PNG.to_vec();
+    png.resize(files::MAX_IMAGE_SIZE as usize + 1, 0);
+    let err = files::store_sniffed_image(&f.store, None, &f.project.id, None, "a.png", &png);
+    assert_eq!(err.unwrap_err(), "media exceeds 10 MB limit");
+}
+
 #[test]
 fn failed_note_save_rolls_back_new_files_but_keeps_previous_media() {
     let f = Fixture::new();
@@ -631,6 +693,42 @@ fn materialization_missing_files_and_remote_video_caps_are_readable() {
     assert!(materialized.contains(&video.size_bytes.to_string()));
 }
 
+/// A PDF attachment is viewed through the same protocol as note media, in an
+/// `<iframe>`: the stored MIME comes back and the viewer can seek with
+/// Range. Only the stored extension resolves; the id cannot be read as an
+/// image.
+#[test]
+fn desktop_protocol_serves_pdf_attachments_with_ranges() {
+    use tauri::http::{Request, StatusCode};
+    let f = Fixture::new();
+    let pdf = super::pdf::tests::tiny_pdf(&[super::pdf::tests::PAGE_ONE]);
+    let image =
+        files::store_sniffed_image(&f.store, None, &f.project.id, None, "doc.pdf", &pdf).unwrap();
+    assert_eq!(
+        serving::lookup(&f.store, &format!("{}.pdf", image.id))
+            .unwrap()
+            .1,
+        "application/pdf"
+    );
+    assert!(serving::lookup(&f.store, &format!("{}.png", image.id)).is_err());
+    let response = serving::response(
+        &f.store,
+        Request::builder()
+            .uri(format!("staged-media://localhost/{}.pdf", image.id))
+            .header("Range", "bytes=0-4")
+            .body(vec![])
+            .unwrap(),
+    );
+    assert_eq!(response.status(), StatusCode::PARTIAL_CONTENT);
+    assert_eq!(response.headers()["content-type"], "application/pdf");
+    assert_eq!(response.headers()["accept-ranges"], "bytes");
+    assert_eq!(
+        response.headers()["content-range"],
+        format!("bytes 0-4/{}", pdf.len())
+    );
+    assert_eq!(response.body(), b"%PDF-");
+}
+
 #[test]
 fn desktop_protocol_seeks_and_handles_head_and_unsatisfiable_ranges() {
     use tauri::http::{Request, StatusCode};
diff --git a/apps/staged/src-tauri/src/pikchr_mcp.rs b/apps/staged/src-tauri/src/pikchr_mcp.rs
index 643afeb83..dd111964b 100644
--- a/apps/staged/src-tauri/src/pikchr_mcp.rs
+++ b/apps/staged/src-tauri/src/pikchr_mcp.rs
@@ -1633,7 +1633,7 @@ arrow from COLL.e to SNOW.w"#;
             &self,
             session_id: &str,
             _prompt: &str,
-            _images: &[(String, String)],
+            _images: &[acp_client::PromptImage],
             _working_dir: &std::path::Path,
             _store: &Arc<dyn acp_client::Store>,
             _writer: &Arc<dyn acp_client::MessageWriter>,
@@ -1725,7 +1725,7 @@ arrow from COLL.e to SNOW.w"#;
             &self,
             _session_id: &str,
             _prompt: &str,
-            _images: &[(String, String)],
+            _images: &[acp_client::PromptImage],
             _working_dir: &std::path::Path,
             _store: &Arc<dyn acp_client::Store>,
             _writer: &Arc<dyn acp_client::MessageWriter>,
diff --git a/apps/staged/src-tauri/src/pikchr_subsession.rs b/apps/staged/src-tauri/src/pikchr_subsession.rs
index ce37772bc..93f660d8d 100644
--- a/apps/staged/src-tauri/src/pikchr_subsession.rs
+++ b/apps/staged/src-tauri/src/pikchr_subsession.rs
@@ -553,7 +553,7 @@ mod tests {
             &self,
             session_id: &str,
             prompt: &str,
-            _images: &[(String, String)],
+            _images: &[acp_client::PromptImage],
             _working_dir: &Path,
             store: &Arc<dyn acp_client::Store>,
             writer: &Arc<dyn acp_client::MessageWriter>,
@@ -1157,7 +1157,7 @@ agent: http=false, sse=false). Select a provider that supports MCP over HTTP/SSE
             &self,
             session_id: &str,
             prompt: &str,
-            images: &[(String, String)],
+            images: &[acp_client::PromptImage],
             working_dir: &Path,
             store: &Arc<dyn acp_client::Store>,
             writer: &Arc<dyn acp_client::MessageWriter>,
diff --git a/apps/staged/src-tauri/src/session_runner.rs b/apps/staged/src-tauri/src/session_runner.rs
index 0938534e9..a5758b2f3 100644
--- a/apps/staged/src-tauri/src/session_runner.rs
+++ b/apps/staged/src-tauri/src/session_runner.rs
@@ -36,6 +36,8 @@
 //! - All write paths in the background thread use `let _ =` or
 //!   `log::error!`, so FK failures are swallowed gracefully.
 
+mod attachments;
+
 use std::cell::Cell;
 use std::collections::HashMap;
 use std::io;
@@ -1359,8 +1361,9 @@ pub fn start_session(
                 driver.with_mcp_servers(required_mcp_servers)
             };
 
-            // Read and base64-encode images for the prompt content blocks.
-            let mut image_data: Vec<(String, String)> = Vec::new();
+            // Read the attachments for the prompt content blocks: images as
+            // they are, PDFs rendered page by page (see `attachments`).
+            let mut attachments = attachments::PromptAttachments::default();
             for image_id in &config.image_ids {
                 match store.get_image(image_id) {
                     Ok(Some(image)) => {
@@ -1371,10 +1374,7 @@ pub fn start_session(
                         ) {
                             Ok(path) => {
                                 if let Ok(bytes) = std::fs::read(&path) {
-                                    use base64::Engine;
-                                    let encoded =
-                                        base64::engine::general_purpose::STANDARD.encode(&bytes);
-                                    image_data.push((encoded, image.mime_type.clone()));
+                                    attachments.add(&image, &bytes);
                                 } else {
                                     log::warn!(
                                         "Failed to read image file for image {image_id}: {}",
@@ -1396,7 +1396,7 @@ pub fn start_session(
                 }
             }
 
-            let mut prompt = config.prompt.clone();
+            let mut prompt = attachments.prompt(&config.prompt);
             let mut agent_session_id = config.agent_session_id.clone();
             let mut repair_attempts = 0;
             let mut include_images = true;
@@ -1409,7 +1409,7 @@ pub fn start_session(
                 let store_trait: Arc<dyn acp_client::Store> = store.clone();
                 let writer_trait: Arc<dyn acp_client::MessageWriter> = writer;
                 let images = if include_images {
-                    image_data.as_slice()
+                    attachments.images.as_slice()
                 } else {
                     &[]
                 };
diff --git a/apps/staged/src-tauri/src/session_runner/attachments.rs b/apps/staged/src-tauri/src/session_runner/attachments.rs
new file mode 100644
index 000000000..efd5f085e
--- /dev/null
+++ b/apps/staged/src-tauri/src/session_runner/attachments.rs
@@ -0,0 +1,541 @@
+//! Chat attachments as prompt content. The ACP agents accept only image
+//! blocks (claude-agent-acp drops blob resources; codex-acp's input items are
+//! text or image), so a PDF attachment is rendered page by page into image
+//! blocks here, each captioned with its page number and filename, within a
+//! page cap, a per-page size cap, and a byte budget shared by every image
+//! block in the prompt; anything left out or unrenderable is reported in the
+//! prompt text rather than silently dropped.
+
+use crate::note_media::pdf::{self, Fit};
+use crate::store::Image;
+use acp_client::PromptImage;
+use base64::Engine;
+
+/// Pages of one PDF rendered into a prompt. Each page is a full image block,
+/// so a long document would otherwise crowd out the conversation.
+pub(crate) const MAX_PROMPT_PAGES: usize = 20;
+
+/// Encoded bytes of every image block in one prompt — attached images and
+/// rendered PDF pages together, however many attachments the message has.
+/// The prompt travels as one JSON-RPC message and the Claude API refuses
+/// requests over 32 MB; 20 MB of encoded bytes is ~27 MB as base64, which
+/// leaves room for the text and the conversation around it.
+pub(crate) const MAX_PROMPT_IMAGE_BYTES: u64 = 20 * 1024 * 1024;
+
+/// Ceiling on one rendered page. The direct Claude API accepts 10 MB of
+/// base64 per image (Bedrock and Vertex less), so 5 MB of encoded bytes
+/// (~6.7 MB as base64) is the conservative ceiling.
+pub(crate) const MAX_PROMPT_IMAGE_SIZE: u64 = 5 * 1024 * 1024;
+
+/// How much of the attachments goes into a prompt. The defaults are the
+/// constants above; tests shrink them, and the render size, to stay fast.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct PromptLimits {
+    /// Pages rendered from one PDF.
+    pub pages: usize,
+    /// Encoded bytes of every image block in the prompt.
+    pub total_bytes: u64,
+    /// Encoded bytes of one rendered page.
+    pub page_bytes: u64,
+    /// Long edge of a rendered page.
+    pub edge_px: u32,
+}
+
+impl Default for PromptLimits {
+    fn default() -> Self {
+        PromptLimits {
+            pages: MAX_PROMPT_PAGES,
+            total_bytes: MAX_PROMPT_IMAGE_BYTES,
+            page_bytes: MAX_PROMPT_IMAGE_SIZE,
+            edge_px: pdf::MAX_EDGE_PX,
+        }
+    }
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+pub(crate) struct PromptAttachments {
+    pub images: Vec<PromptImage>,
+    /// Appended to the prompt text: attachments that could not be sent as
+    /// images, and why.
+    pub notes: Vec<String>,
+    limits: PromptLimits,
+    /// Encoded bytes of the image blocks accepted so far, against
+    /// `limits.total_bytes`.
+    used_bytes: u64,
+}
+
+impl PromptAttachments {
+    /// Tests shrink the limits so budget cases render in milliseconds.
+    #[cfg(test)]
+    fn with_limits(limits: PromptLimits) -> Self {
+        PromptAttachments {
+            limits,
+            ..Self::default()
+        }
+    }
+
+    pub(crate) fn add(&mut self, image: &Image, bytes: &[u8]) {
+        if image.mime_type != "application/pdf" {
+            if !self.reserve(bytes.len()) {
+                self.notes.push(format!(
+                    "[Attached image {} ({} bytes) not included in this prompt: {}]",
+                    image.filename,
+                    bytes.len(),
+                    self.over_budget()
+                ));
+                return;
+            }
+            self.images
+                .push(PromptImage::new(encode(bytes), image.mime_type.clone()));
+            return;
+        }
+        let document = match pdf::Document::open(bytes) {
+            Ok(document) => document,
+            Err(e) => {
+                log::warn!(
+                    "Cannot render PDF attachment {} for the prompt: {e}",
+                    image.id
+                );
+                self.notes.push(format!(
+                    "[Attached PDF {} ({} bytes) could not be rendered for this prompt: {e}]",
+                    image.filename, image.size_bytes
+                ));
+                return;
+            }
+        };
+        let total = document.page_count();
+        let limits = self.limits;
+        let fit = Fit {
+            max_bytes: limits.page_bytes,
+            jpeg_fallback: true,
+        };
+        let first_image = self.images.len();
+        // Pages are rendered in order and only as far as they are accepted,
+        // so memory holds the accepted set plus the page being decided.
+        let mut omitted: Option<(usize, String)> = None;
+        for page in 1..=total {
+            if page > limits.pages {
+                omitted = Some((page, format!("over the {}-page limit", limits.pages)));
+                break;
+            }
+            // A spent budget refuses every page, so none is rendered only to
+            // be turned away.
+            if self.used_bytes >= limits.total_bytes {
+                omitted = Some((page, self.over_budget()));
+                break;
+            }
+            let encoded = match document.render_page(page, limits.edge_px, fit) {
+                Ok(encoded) => encoded,
+                Err(e) => {
+                    log::warn!(
+                        "Cannot render page {page} of PDF attachment {} for the prompt: {e}",
+                        image.id
+                    );
+                    self.notes.push(format!(
+                        "[Page {page} of {} could not be included in this prompt: {e}]",
+                        image.filename
+                    ));
+                    continue;
+                }
+            };
+            if !self.reserve(encoded.bytes.len()) {
+                omitted = Some((page, self.over_budget()));
+                break;
+            }
+            self.images.push(
+                PromptImage::new(encode(&encoded.bytes), encoded.mime_type)
+                    .with_label(format!("page {page} of {total} of {}", image.filename)),
+            );
+        }
+        if let Some((first, reason)) = omitted {
+            let pages = if first == total {
+                format!("page {total}")
+            } else {
+                format!("pages {first}–{total}")
+            };
+            let what = format!("{pages} not included: {reason}");
+            // Said on the last page sent, where the agent is reading page
+            // numbers; in the prompt text when no page made it.
+            if self.images.len() > first_image {
+                if let Some(label) = self.images.last_mut().and_then(|last| last.label.as_mut()) {
+                    label.push_str(&format!(" ({what})"));
+                }
+            } else {
+                self.notes
+                    .push(format!("[Attached PDF {}: {what}]", image.filename));
+            }
+        }
+    }
+
+    /// Count `len` encoded bytes against the prompt's image budget; false,
+    /// with nothing counted, when they would cross it.
+    fn reserve(&mut self, len: usize) -> bool {
+        let len = len as u64;
+        if self.used_bytes + len > self.limits.total_bytes {
+            return false;
+        }
+        self.used_bytes += len;
+        true
+    }
+
+    fn over_budget(&self) -> String {
+        format!(
+            "over the {} image budget",
+            describe_size(self.limits.total_bytes)
+        )
+    }
+
+    /// The prompt text with the notes, if any, after it.
+    pub(crate) fn prompt(&self, prompt: &str) -> String {
+        let mut prompt = prompt.to_owned();
+        for note in &self.notes {
+            prompt.push_str("\n\n");
+            prompt.push_str(note);
+        }
+        prompt
+    }
+}
+
+fn encode(bytes: &[u8]) -> String {
+    base64::engine::general_purpose::STANDARD.encode(bytes)
+}
+
+/// Whole MB or KB where the size is one, else bytes: the shipped budget reads
+/// "20 MB", a test's "3 KB".
+fn describe_size(bytes: u64) -> String {
+    const KB: u64 = 1024;
+    const MB: u64 = KB * KB;
+    if bytes >= MB && bytes % MB == 0 {
+        format!("{} MB", bytes / MB)
+    } else if bytes >= KB && bytes % KB == 0 {
+        format!("{} KB", bytes / KB)
+    } else {
+        format!("{bytes} bytes")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::note_media::pdf::tests::{tiny_pdf, PAGE_ONE, PAGE_TWO};
+    use crate::note_media::tests::PNG;
+
+    fn image(filename: &str, mime_type: &str, size: usize) -> Image {
+        Image::new(None, "project", filename, mime_type, size as i64, false)
+    }
+
+    fn png_image() -> Image {
+        image("shot.png", "image/png", PNG.len())
+    }
+
+    /// Letter pages at a 256 px long edge: enough to tell the pages apart,
+    /// cheap enough to render dozens.
+    fn small(limits: PromptLimits) -> PromptAttachments {
+        PromptAttachments::with_limits(PromptLimits {
+            edge_px: 256,
+            ..limits
+        })
+    }
+
+    fn budget(total_bytes: u64) -> PromptAttachments {
+        small(PromptLimits {
+            total_bytes,
+            ..PromptLimits::default()
+        })
+    }
+
+    #[test]
+    fn images_are_sent_as_they_are_stored() {
+        let mut attachments = PromptAttachments::default();
+        attachments.add(&png_image(), PNG);
+        assert_eq!(
+            attachments.images,
+            [PromptImage::new(encode(PNG), "image/png")]
+        );
+        assert!(attachments.notes.is_empty());
+        assert_eq!(attachments.prompt("look"), "look");
+    }
+
+    #[test]
+    fn images_over_the_budget_are_noted_not_dropped() {
+        let total_bytes = PNG.len() as u64 * 3 / 2;
+        let mut attachments = budget(total_bytes);
+        attachments.add(&png_image(), PNG);
+        attachments.add(&image("second.png", "image/png", PNG.len()), PNG);
+        assert_eq!(attachments.images.len(), 1);
+        assert_eq!(
+            attachments.notes,
+            [format!(
+                "[Attached image second.png ({} bytes) not included in this prompt: over the {} image budget]",
+                PNG.len(),
+                describe_size(total_bytes)
+            )]
+        );
+        // The refused image was not counted, so a smaller one still fits.
+        attachments.add(&image("tiny.gif", "image/gif", 1), &PNG[..PNG.len() / 2]);
+        assert_eq!(attachments.images.len(), 2);
+        assert_eq!(attachments.notes.len(), 1);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn pdf_pages_become_captioned_png_images() {
+        let pdf = tiny_pdf(&[PAGE_ONE, PAGE_TWO]);
+        let mut attachments = PromptAttachments::default();
+        attachments.add(&image("report.pdf", "application/pdf", pdf.len()), &pdf);
+        assert!(attachments.notes.is_empty());
+        assert_eq!(attachments.images.len(), 2);
+        for (index, prompt_image) in attachments.images.iter().enumerate() {
+            assert_eq!(prompt_image.mime_type, "image/png");
+            assert_eq!(
+                prompt_image.label.as_deref(),
+                Some(format!("page {} of 2 of report.pdf", index + 1).as_str())
+            );
+            let png = base64::engine::general_purpose::STANDARD
+                .decode(&prompt_image.data)
+                .unwrap();
+            let pixmap = tiny_skia::Pixmap::decode_png(&png).unwrap();
+            assert_eq!((pixmap.width(), pixmap.height()), (1545, 2000));
+        }
+        // The pages differ: page two's rule at y=400pt is only on page two.
+        let row = ((792.0 - 400.0) * f64::from(pdf::MAX_EDGE_PX) / 792.0) as u32;
+        let pixel = |i: usize| {
+            let png = base64::engine::general_purpose::STANDARD
+                .decode(&attachments.images[i].data)
+                .unwrap();
+            tiny_skia::Pixmap::decode_png(&png)
+                .unwrap()
+                .pixel(800, row)
+                .unwrap()
+                .red()
+        };
+        assert_eq!(pixel(0), 255);
+        assert!(pixel(1) < 128);
+    }
+
+    /// Encoded size of one small [`PAGE_ONE`] render, for budgets.
+    #[cfg(target_os = "macos")]
+    fn small_page_bytes() -> u64 {
+        let document = pdf::Document::open(&tiny_pdf(&[PAGE_ONE])).unwrap();
+        let fit = Fit {
+            max_bytes: MAX_PROMPT_IMAGE_SIZE,
+            jpeg_fallback: true,
+        };
+        document.render_page(1, 256, fit).unwrap().bytes.len() as u64
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn long_pdfs_stop_at_the_page_cap_and_say_so() {
+        let pages = vec![PAGE_ONE; MAX_PROMPT_PAGES + 5];
+        let pdf = tiny_pdf(&pages);
+        let mut attachments = small(PromptLimits::default());
+        attachments.add(&image("long.pdf", "application/pdf", pdf.len()), &pdf);
+        assert_eq!(attachments.images.len(), MAX_PROMPT_PAGES);
+        assert!(attachments.notes.is_empty());
+        assert_eq!(
+            attachments.images[MAX_PROMPT_PAGES - 2].label.as_deref(),
+            Some("page 19 of 25 of long.pdf")
+        );
+        assert_eq!(
+            attachments.images[MAX_PROMPT_PAGES - 1].label.as_deref(),
+            Some("page 20 of 25 of long.pdf (pages 21–25 not included: over the 20-page limit)")
+        );
+        let png = base64::engine::general_purpose::STANDARD
+            .decode(&attachments.images[0].data)
+            .unwrap();
+        assert_eq!(tiny_skia::Pixmap::decode_png(&png).unwrap().width(), 198);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn pages_stop_at_the_byte_budget_and_say_so() {
+        let page_bytes = small_page_bytes();
+        let pdf = tiny_pdf(&[PAGE_ONE; 4]);
+        let pdf_image = image("scan.pdf", "application/pdf", pdf.len());
+
+        // Two pages fit; the third would cross the budget, so it and the
+        // rest are left out and the last page sent says so.
+        let mut attachments = budget(page_bytes * 5 / 2);
+        attachments.add(&pdf_image, &pdf);
+        assert_eq!(attachments.images.len(), 2);
+        assert!(attachments.notes.is_empty());
+        assert_eq!(
+            attachments.images[1].label.as_deref(),
+            Some(
+                format!(
+                    "page 2 of 4 of scan.pdf (pages 3–4 not included: over the {} image budget)",
+                    describe_size(page_bytes * 5 / 2)
+                )
+                .as_str()
+            )
+        );
+
+        // A single page left out is named as one.
+        let mut attachments = budget(page_bytes * 3);
+        attachments.add(&pdf_image, &pdf);
+        assert_eq!(attachments.images.len(), 3);
+        let label = attachments.images[2].label.as_deref().unwrap();
+        assert!(
+            label.starts_with("page 3 of 4 of scan.pdf (page 4 not included: over the "),
+            "{label}"
+        );
+
+        // When not even the first page fits, the prompt text carries the note
+        // and no label from an earlier attachment is touched.
+        let mut attachments = budget(page_bytes - 1);
+        attachments.add(&image("tiny.png", "image/png", 1), &[0u8; 1]);
+        attachments.add(&pdf_image, &pdf);
+        assert_eq!(attachments.images.len(), 1);
+        assert_eq!(attachments.images[0].label, None);
+        assert_eq!(attachments.notes.len(), 1);
+        assert!(
+            attachments.notes[0]
+                .starts_with("[Attached PDF scan.pdf: pages 1–4 not included: over the "),
+            "{}",
+            attachments.notes[0]
+        );
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn the_byte_budget_is_shared_by_every_attachment_in_the_prompt() {
+        let page_bytes = small_page_bytes();
+        let pdf = tiny_pdf(&[PAGE_ONE, PAGE_ONE]);
+        let first = image("a.pdf", "application/pdf", pdf.len());
+        let second = image("b.pdf", "application/pdf", pdf.len());
+
+        // Two PDFs: the first takes two of the three pages the budget
+        // holds, so the second gets one page and names the one left out.
+        let mut attachments = budget(page_bytes * 7 / 2);
+        attachments.add(&first, &pdf);
+        attachments.add(&second, &pdf);
+        assert!(attachments.notes.is_empty());
+        let labels: Vec<_> = attachments
+            .images
+            .iter()
+            .map(|image| image.label.as_deref().unwrap())
+            .collect();
+        assert_eq!(
+            labels,
+            [
+                "page 1 of 2 of a.pdf",
+                "page 2 of 2 of a.pdf",
+                &format!(
+                    "page 1 of 2 of b.pdf (page 2 not included: over the {} image budget)",
+                    describe_size(page_bytes * 7 / 2)
+                ),
+            ]
+        );
+
+        // An image before a PDF counts against the same budget: the PDF
+        // gets the one page that is left.
+        let mut attachments = budget(PNG.len() as u64 + page_bytes * 3 / 2);
+        attachments.add(&png_image(), PNG);
+        attachments.add(&first, &pdf);
+        assert!(attachments.notes.is_empty());
+        assert_eq!(attachments.images.len(), 2);
+        assert_eq!(attachments.images[0].label, None);
+        assert!(attachments.images[1]
+            .label
+            .as_deref()
+            .unwrap()
+            .starts_with("page 1 of 2 of a.pdf (page 2 not included: over the "),);
+
+        // A PDF that uses the budget up leaves a later image noted in the
+        // prompt text, with the PDF's own pages and labels untouched.
+        let mut attachments = budget(page_bytes * 2);
+        attachments.add(&first, &pdf);
+        attachments.add(&png_image(), PNG);
+        assert_eq!(attachments.images.len(), 2);
+        assert_eq!(
+            attachments.images[1].label.as_deref(),
+            Some("page 2 of 2 of a.pdf")
+        );
+        assert_eq!(
+            attachments.notes,
+            [format!(
+                "[Attached image shot.png ({} bytes) not included in this prompt: over the {} image budget]",
+                PNG.len(),
+                describe_size(page_bytes * 2)
+            )]
+        );
+        // A later PDF finds the budget spent before its first page is
+        // rendered and is noted in the prompt text like one that did not fit.
+        attachments.add(&second, &pdf);
+        assert_eq!(attachments.images.len(), 2);
+        assert_eq!(attachments.notes.len(), 2);
+        assert_eq!(
+            attachments.notes[1],
+            format!(
+                "[Attached PDF b.pdf: pages 1–2 not included: over the {} image budget]",
+                describe_size(page_bytes * 2)
+            )
+        );
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn pages_over_the_per_page_cap_are_noted_and_the_rest_still_sent() {
+        let pdf = tiny_pdf(&[PAGE_ONE, PAGE_TWO]);
+        // Under the smallest text page even as a JPEG: every page is refused
+        // on its own, each with a note, and nothing stops the loop.
+        let mut attachments = small(PromptLimits {
+            page_bytes: 64,
+            ..PromptLimits::default()
+        });
+        attachments.add(&image("scan.pdf", "application/pdf", pdf.len()), &pdf);
+        assert!(attachments.images.is_empty());
+        assert_eq!(attachments.notes.len(), 2);
+        assert!(
+            attachments.notes[0].starts_with(
+                "[Page 1 of scan.pdf could not be included in this prompt: PDF page exceeds"
+            ),
+            "{}",
+            attachments.notes[0]
+        );
+        assert!(attachments.notes[1].starts_with("[Page 2 of scan.pdf"));
+
+        // The shipped per-page cap is far above a rendered text page.
+        assert!(small_page_bytes() < MAX_PROMPT_IMAGE_SIZE / 100);
+    }
+
+    #[test]
+    fn sizes_read_in_whole_units() {
+        assert_eq!(describe_size(MAX_PROMPT_IMAGE_BYTES), "20 MB");
+        assert_eq!(describe_size(3 * 1024), "3 KB");
+        assert_eq!(describe_size(1500), "1500 bytes");
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn unrenderable_pdfs_are_reported_in_the_prompt() {
+        let bytes = b"%PDF-1.4\nnot really";
+        let mut attachments = PromptAttachments::default();
+        attachments.add(&image("bad.pdf", "application/pdf", bytes.len()), bytes);
+        assert!(attachments.images.is_empty());
+        assert_eq!(attachments.notes.len(), 1);
+        let prompt = attachments.prompt("look at this");
+        assert!(
+            prompt.starts_with(
+                "look at this\n\n[Attached PDF bad.pdf (19 bytes) could not be rendered"
+            ),
+            "{prompt}"
+        );
+        assert!(prompt.contains("PDF"), "{prompt}");
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn pdfs_are_reported_where_they_cannot_be_rendered() {
+        let pdf = tiny_pdf(&[PAGE_ONE, PAGE_TWO]);
+        let mut attachments = PromptAttachments::default();
+        attachments.add(&image("report.pdf", "application/pdf", pdf.len()), &pdf);
+        assert!(attachments.images.is_empty());
+        let prompt = attachments.prompt("look");
+        assert!(
+            prompt.contains("report.pdf") && prompt.contains("macOS"),
+            "{prompt}"
+        );
+    }
+}
diff --git a/apps/staged/src-tauri/src/store/images.rs b/apps/staged/src-tauri/src/store/images.rs
index 1be3cfeb3..4f178914f 100644
--- a/apps/staged/src-tauri/src/store/images.rs
+++ b/apps/staged/src-tauri/src/store/images.rs
@@ -1,6 +1,7 @@
 //! Image CRUD operations and filesystem helpers.
 
 use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
 
 use rusqlite::{params, OptionalExtension};
 
@@ -167,10 +168,12 @@ impl Store {
     }
 
     /// Return chat attachments linked to a session, excluding note-owned media
-    /// so restarted sessions don't send videos as ACP image input.
+    /// so restarted sessions don't send videos as ACP image input. PDFs are
+    /// chat attachments too; the runner renders their pages for the prompt.
     pub fn get_image_ids_for_session(&self, session_id: &str) -> Result<Vec<String>, StoreError> {
         let conn = self.conn.lock().unwrap();
-        let mut stmt = conn.prepare("SELECT id FROM images WHERE session_id = ?1 AND mime_type LIKE 'image/%'
+        let mut stmt = conn.prepare("SELECT id FROM images WHERE session_id = ?1
+             AND (mime_type LIKE 'image/%' OR mime_type = 'application/pdf')
              AND NOT EXISTS (SELECT 1 FROM notes WHERE instr(content, 'staged-media://' || images.id || '.') > 0)
              AND NOT EXISTS (SELECT 1 FROM project_notes WHERE instr(content, 'staged-media://' || images.id || '.') > 0)")?;
         let ids = stmt
@@ -215,9 +218,7 @@ impl Store {
 
         let count = rows.len();
         for (id, project_id, filename) in &rows {
-            if let Ok(path) = image_file_path(project_id, id, filename) {
-                let _ = std::fs::remove_file(path);
-            }
+            remove_image_files(project_id, id, filename);
         }
 
         conn.execute(
@@ -298,3 +299,62 @@ pub fn image_file_path(
         .join("images")
         .join(format!("{image_id}.{ext}")))
 }
+
+/// Where the rendered first-page thumbnail of a PDF attachment is cached,
+/// beside the PDF itself: `<project_worktree_root>/images/<image_id>.thumb.png`.
+/// The `.thumb.png` suffix cannot collide with [`image_file_path`], whose
+/// names are a bare UUID plus one extension.
+pub fn thumbnail_file_path(project_id: &str, image_id: &str) -> Result<PathBuf, String> {
+    let project_root = crate::git::project_worktree_root_for(project_id)
+        .map_err(|e| format!("Cannot determine project root: {e}"))?;
+    Ok(project_root
+        .join("images")
+        .join(format!("{image_id}.thumb.png")))
+}
+
+/// Where a thumbnail is written before it is renamed over
+/// [`thumbnail_file_path`], so a reader sees either no cache or a complete
+/// one: `<project_worktree_root>/images/<image_id>.thumb.<pid>-<n>.tmp`.
+/// Unique per writer, so two slots rendering the same new attachment at
+/// once never interleave into one file; whichever rename lands last wins,
+/// and both are complete PNGs of the same page.
+pub fn thumbnail_temp_file_path(project_id: &str, image_id: &str) -> Result<PathBuf, String> {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let project_root = crate::git::project_worktree_root_for(project_id)
+        .map_err(|e| format!("Cannot determine project root: {e}"))?;
+    Ok(project_root.join("images").join(format!(
+        "{image_id}.thumb.{}-{}.tmp",
+        std::process::id(),
+        COUNTER.fetch_add(1, Ordering::Relaxed)
+    )))
+}
+
+/// Best-effort removal of an image's file, any cached thumbnail, and any
+/// thumbnail temp file a crash left behind, for the delete paths. A file
+/// that is already gone is not worth a warning.
+pub fn remove_image_files(project_id: &str, image_id: &str, filename: &str) {
+    let mut paths: Vec<PathBuf> = [
+        image_file_path(project_id, image_id, filename),
+        thumbnail_file_path(project_id, image_id),
+    ]
+    .into_iter()
+    .flatten()
+    .collect();
+    if let Some(dir) = paths.first().and_then(|p| p.parent()) {
+        let prefix = format!("{image_id}.thumb.");
+        if let Ok(entries) = std::fs::read_dir(dir) {
+            paths.extend(entries.flatten().map(|e| e.path()).filter(|p| {
+                p.file_name()
+                    .and_then(|n| n.to_str())
+                    .is_some_and(|n| n.starts_with(&prefix) && n.ends_with(".tmp"))
+            }));
+        }
+    }
+    for path in paths {
+        if let Err(e) = std::fs::remove_file(&path) {
+            if e.kind() != std::io::ErrorKind::NotFound {
+                log::warn!("Failed to remove image file {}: {e}", path.display());
+            }
+        }
+    }
+}
diff --git a/apps/staged/src-tauri/src/web_server.rs b/apps/staged/src-tauri/src/web_server.rs
index c2dab66be..d560a58fc 100644
--- a/apps/staged/src-tauri/src/web_server.rs
+++ b/apps/staged/src-tauri/src/web_server.rs
@@ -23,7 +23,7 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use axum::extract::ws::{Message, WebSocket};
-use axum::extract::{Path, Query, Request, State, WebSocketUpgrade};
+use axum::extract::{DefaultBodyLimit, Path, Query, Request, State, WebSocketUpgrade};
 use axum::http::StatusCode;
 use axum::middleware::{self, Next};
 use axum::response::{IntoResponse, Json, Response};
@@ -243,8 +243,7 @@ pub(crate) fn app_router(state: WebAppState, dist_dir: &std::path::Path) -> Rout
         }
     };
 
-    Router::new()
-        .route("/api/invoke/{command}", post(invoke_command))
+    invoke_router(invoke_command)
         .route("/api/events", get(ws_events))
         .with_state(state)
         .merge(media_routes)
@@ -253,6 +252,30 @@ pub(crate) fn app_router(state: WebAppState, dist_dir: &std::path::Path) -> Rout
         .layer(CorsLayer::permissive())
 }
 
+/// Request body cap for `/api/invoke/{command}`, the only route that takes a
+/// large body. axum's default is 2 MiB, which would refuse a base64 PDF
+/// attachment before `create_image_from_data`'s own
+/// [`MAX_PDF_INPUT_SIZE`](crate::note_media::files::MAX_PDF_INPUT_SIZE) check
+/// ever sees it, so this is the base64 of a cap-sized payload plus a margin
+/// for the JSON envelope (the other arguments are short strings).
+const INVOKE_BODY_LIMIT: usize =
+    (crate::note_media::files::MAX_PDF_INPUT_SIZE.div_ceil(3) * 4) as usize + 64 * 1024;
+
+/// The invoke route with its body limit applied to that route alone. Generic
+/// over the handler so a test can mount a stand-in without a Tauri
+/// `AppHandle` and exercise the exact layering [`app_router`] uses.
+fn invoke_router<S, H, T>(handler: H) -> Router<S>
+where
+    H: axum::handler::Handler<T, S>,
+    T: 'static,
+    S: Clone + Send + Sync + 'static,
+{
+    Router::new().route(
+        "/api/invoke/{command}",
+        post(handler).layer(DefaultBodyLimit::max(INVOKE_BODY_LIMIT)),
+    )
+}
+
 /// Kept ready for the mobile-web startup restore. The route and auth layer are
 /// exercised together by oneshot tests, without starting a listener.
 pub(crate) fn media_router(state: WebAppState) -> Result<Router, String> {
@@ -277,6 +300,12 @@ pub(crate) fn media_router(state: WebAppState) -> Result<Router, String> {
 /// `<img>` rendering ignores response CSP, so this costs nothing there.
 const UNTRUSTED_MEDIA_CSP: &str = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
 
+/// A PDF attachment is shown in an `<iframe>` by the browser's own viewer,
+/// which WebKit treats as a plugin and refuses in a sandboxed document (the
+/// frame stays blank). The viewer runs no page-origin script, so only
+/// `sandbox` is dropped for it.
+const UNTRUSTED_PDF_CSP: &str = "default-src 'none'; style-src 'unsafe-inline'";
+
 fn media_router_for_store(
     store: Arc<Store>,
     token: String,
@@ -327,9 +356,14 @@ async fn serve_media(
             );
             // `mime_for_extension` has no SVG entry today; this keeps a future
             // one from reopening the top-level script hole.
+            let csp = if mime == "application/pdf" {
+                UNTRUSTED_PDF_CSP
+            } else {
+                UNTRUSTED_MEDIA_CSP
+            };
             response.headers_mut().insert(
                 axum::http::header::CONTENT_SECURITY_POLICY,
-                axum::http::HeaderValue::from_static(UNTRUSTED_MEDIA_CSP),
+                axum::http::HeaderValue::from_static(csp),
             );
             response
         }
@@ -2851,9 +2885,13 @@ async fn dispatch(command: &str, args: Value, state: &WebAppState) -> Result<Val
             let mime_type: String = arg(&args, "mimeType")?;
             let data: String = arg(&args, "data")?;
             let pending: Option<bool> = opt_arg(&args, "pending")?;
-            let image = crate::image_commands::create_image_from_data_impl(
-                store, branch_id, project_id, filename, mime_type, data, pending,
-            )?;
+            let image = tauri::async_runtime::spawn_blocking(move || {
+                crate::image_commands::create_image_from_data_impl(
+                    store, branch_id, project_id, filename, mime_type, data, pending,
+                )
+            })
+            .await
+            .map_err(|e| format!("Image task failed: {e}"))??;
             Ok(serde_json::to_value(image).unwrap())
         }
         "get_image_path" => {
@@ -2902,13 +2940,19 @@ async fn dispatch(command: &str, args: Value, state: &WebAppState) -> Result<Val
                 .map_err(|e| e.to_string())?
                 .ok_or_else(|| format!("Image not found: {image_id}"))?;
             store.delete_image(&image_id).map_err(|e| e.to_string())?;
-            if let Ok(path) =
-                crate::store::images::image_file_path(&image.project_id, &image.id, &image.filename)
-            {
-                let _ = std::fs::remove_file(&path);
-            }
+            crate::store::images::remove_image_files(&image.project_id, &image.id, &image.filename);
             Ok(Value::Null)
         }
+        "get_attachment_thumbnail" => {
+            let store = get_store(store_mutex)?;
+            let image_id: String = arg(&args, "imageId")?;
+            let thumbnail = tauri::async_runtime::spawn_blocking(move || {
+                crate::image_commands::attachment_thumbnail_impl(&store, &image_id)
+            })
+            .await
+            .map_err(|e| format!("Thumbnail task failed: {e}"))??;
+            Ok(serde_json::to_value(thumbnail).unwrap())
+        }
         "list_branch_images" => {
             let store = get_store(store_mutex)?;
             let branch_id: String = arg(&args, "branchId")?;
@@ -4467,12 +4511,150 @@ mod tests {
     }
 }
 
+#[cfg(test)]
+mod invoke_tests {
+    use super::*;
+    use tower::ServiceExt;
+
+    /// Stands in for `invoke_command` with the same extractors, reporting what
+    /// reached dispatch so the test can tell a parsed body from a refused one.
+    async fn echo_len(Path(command): Path<String>, Json(args): Json<Value>) -> Json<Value> {
+        let data_len = args["data"].as_str().map_or(0, str::len);
+        Json(serde_json::json!({ "command": command, "dataLen": data_len }))
+    }
+
+    fn invoke(body: String) -> axum::http::Request<axum::body::Body> {
+        axum::http::Request::builder()
+            .method("POST")
+            .uri("/api/invoke/create_image_from_data")
+            .header("Content-Type", "application/json")
+            .body(axum::body::Body::from(body))
+            .unwrap()
+    }
+
+    #[tokio::test]
+    async fn invoke_route_admits_a_cap_sized_pdf_body_and_refuses_larger() {
+        let router: Router = invoke_router(echo_len);
+
+        // The base64 of a PDF right at MAX_PDF_INPUT_SIZE: the largest body
+        // `create_image_from_data` admits, and far past axum's 2 MiB default.
+        let data_len = (crate::note_media::files::MAX_PDF_INPUT_SIZE.div_ceil(3) * 4) as usize;
+        let body = format!(r#"{{"data":"{}"}}"#, "A".repeat(data_len));
+        assert!(body.len() > 2 * 1024 * 1024 && body.len() <= INVOKE_BODY_LIMIT);
+        let response = router.clone().oneshot(invoke(body)).await.unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let bytes = axum::body::to_bytes(response.into_body(), 1024)
+            .await
+            .unwrap();
+        let reply: Value = serde_json::from_slice(&bytes).unwrap();
+        assert_eq!(reply["command"], "create_image_from_data");
+        assert_eq!(reply["dataLen"], data_len);
+
+        // One byte over the limit never reaches the handler.
+        let body = format!(r#"{{"data":"{}"}}"#, "A".repeat(INVOKE_BODY_LIMIT - 10));
+        assert_eq!(body.len(), INVOKE_BODY_LIMIT + 1);
+        let response = router.oneshot(invoke(body)).await.unwrap();
+        assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
+        // axum answers with a plain-text rejection, not the `{ "error" }` JSON
+        // `invoke_command` emits, so `transport.ts` surfaces this text as-is.
+        let text = axum::body::to_bytes(response.into_body(), 1024)
+            .await
+            .unwrap();
+        let text = std::str::from_utf8(&text).unwrap();
+        assert!(
+            serde_json::from_str::<Value>(text).is_err(),
+            "unexpected JSON body: {text}"
+        );
+    }
+}
+
 #[cfg(test)]
 mod media_tests {
     use super::*;
     use crate::note_media::tests::{Fixture, PNG};
     use tower::ServiceExt;
 
+    /// The browser's PDF viewer loads a PDF attachment in an `<iframe>`, so
+    /// the response keeps the stored MIME and Range support but must not
+    /// carry the `sandbox` directive, which blanks the viewer in WebKit.
+    #[tokio::test]
+    async fn pdf_media_is_served_without_the_sandbox_directive() {
+        let fixture = Fixture::new();
+        let pdf =
+            crate::note_media::pdf::tests::tiny_pdf(&[crate::note_media::pdf::tests::PAGE_ONE]);
+        let image = crate::note_media::files::store_sniffed_image(
+            &fixture.store,
+            None,
+            &fixture.project.id,
+            None,
+            "doc.pdf",
+            &pdf,
+        )
+        .unwrap();
+        let sessions = Arc::new(Mutex::new(HashSet::new()));
+        let router = media_router_for_store(fixture.store.clone(), "bearer-token".into(), sessions);
+        let request = |uri: String, range: Option<&str>| {
+            let mut request = axum::http::Request::builder()
+                .uri(uri)
+                .header("Authorization", "Bearer bearer-token");
+            if let Some(range) = range {
+                request = request.header("Range", range);
+            }
+            request.body(axum::body::Body::empty()).unwrap()
+        };
+        let response = router
+            .clone()
+            .oneshot(request(format!("/api/media/{}.pdf", image.id), None))
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        assert_eq!(response.headers()["content-type"], "application/pdf");
+        assert_eq!(response.headers()["x-content-type-options"], "nosniff");
+        assert_eq!(
+            response.headers()["content-security-policy"],
+            UNTRUSTED_PDF_CSP
+        );
+        assert!(!UNTRUSTED_PDF_CSP.contains("sandbox"));
+        assert_eq!(
+            axum::body::to_bytes(response.into_body(), usize::MAX)
+                .await
+                .unwrap()
+                .as_ref(),
+            &pdf[..]
+        );
+
+        let response = router
+            .clone()
+            .oneshot(request(
+                format!("/api/media/{}.pdf", image.id),
+                Some("bytes=0-4"),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::PARTIAL_CONTENT);
+        assert_eq!(response.headers()["accept-ranges"], "bytes");
+        assert_eq!(
+            axum::body::to_bytes(response.into_body(), 100)
+                .await
+                .unwrap()
+                .as_ref(),
+            b"%PDF-"
+        );
+
+        // Images keep the sandboxed policy.
+        std::fs::write(fixture.dir.path().join("shot.png"), PNG).unwrap();
+        let outcome = fixture.ingest("", "![a](shot.png)");
+        let id = outcome.kept_ids.iter().next().unwrap();
+        let response = router
+            .oneshot(request(format!("/api/media/{id}.png"), None))
+            .await
+            .unwrap();
+        assert_eq!(
+            response.headers()["content-security-policy"],
+            UNTRUSTED_MEDIA_CSP
+        );
+    }
+
     #[tokio::test]
     async fn media_route_requires_auth_and_streams_ranges() {
         let fixture = Fixture::new();
diff --git a/apps/staged/src/lib/commands.ts b/apps/staged/src/lib/commands.ts
index 87a358cf2..877b9dad7 100644
--- a/apps/staged/src/lib/commands.ts
+++ b/apps/staged/src/lib/commands.ts
@@ -48,6 +48,7 @@ import type {
   PrStatus,
   PollWorkspaceResult,
   Image,
+  AttachmentThumbnail,
   SuggestedRepo,
   AcpConfigSelection,
 } from './types';
@@ -1934,11 +1935,19 @@ export function listBranchImages(branchId: string): Promise<Image[]> {
   return invokeCommand('list_branch_images', { branchId });
 }
 
-/** Get the base64-encoded data URL for an image. */
+/** Get the base64-encoded data URL for an image (or the PDF itself, for a PDF attachment). */
 export function getImageData(imageId: string): Promise<string> {
   return invokeCommand('get_image_data', { imageId });
 }
 
+/**
+ * Small preview of an attachment: the image itself, or for a PDF a PNG of its
+ * first page (rendered once and cached by the backend).
+ */
+export function getAttachmentThumbnail(imageId: string): Promise<AttachmentThumbnail> {
+  return invokeCommand('get_attachment_thumbnail', { imageId });
+}
+
 /** Load an image referenced by a tool result without creating an attachment. */
 export function readImageFile(filePath: string): Promise<string> {
   return invokeCommand('read_image_file', { filePath });
diff --git a/apps/staged/src/lib/features/branches/BranchCard.svelte b/apps/staged/src/lib/features/branches/BranchCard.svelte
index 6ac06c662..998f6116c 100644
--- a/apps/staged/src/lib/features/branches/BranchCard.svelte
+++ b/apps/staged/src/lib/features/branches/BranchCard.svelte
@@ -62,6 +62,7 @@
   import NoteModal from '../notes/NoteModal.svelte';
   import WriteNoteModal from '../notes/WriteNoteModal.svelte';
   import { splitNoteMarkdown } from '../notes/noteMarkdown';
+  import { attachBasename } from '../sessions/attachErrors';
   import * as AlertDialog from '$lib/components/ui/alert-dialog';
   import { Button } from '$lib/components/ui/button';
   import {
@@ -72,7 +73,7 @@
     formatBaseBranch,
     isGitActionInFlight,
     isMaybeTextFile,
-    isImageFile,
+    isImageAttachmentFile,
   } from './branchCardHelpers';
   import BranchCardHeaderInfo from './BranchCardHeaderInfo.svelte';
   import BranchCardActionsBar from './BranchCardActionsBar.svelte';
@@ -1737,7 +1738,7 @@
 
   function handleFileDrop(paths: string[]) {
     const textPaths = paths.filter(isMaybeTextFile);
-    const imagePaths = paths.filter(isImageFile);
+    const imagePaths = paths.filter(isImageAttachmentFile);
 
     if (textPaths.length > 0) {
       const placeholders = textPaths.map((filePath) => ({
@@ -1778,6 +1779,14 @@
             await commands.createImage(branch.id, branch.projectId, filePath);
           } catch (e) {
             console.error('Failed to create image from drop:', e);
+            // Same shape as the text path, so a rejected PDF or oversized
+            // image ("could not open PDF", "media exceeds 10 MB limit") is
+            // not a silent no-op. The extension stays in the name, as in the
+            // composer's attach errors: it is what explains a PDF failure.
+            const reason = e instanceof Error ? e.message : typeof e === 'string' ? e : null;
+            toast.error('Error', {
+              description: `Could not attach "${attachBasename(filePath)}"${reason ? ` \u2014 ${reason}` : ''}`,
+            });
           }
         })
       ).then(() => {
diff --git a/apps/staged/src/lib/features/branches/branchCardHelpers.test.ts b/apps/staged/src/lib/features/branches/branchCardHelpers.test.ts
index a5a0129cf..d6c0b6f96 100644
--- a/apps/staged/src/lib/features/branches/branchCardHelpers.test.ts
+++ b/apps/staged/src/lib/features/branches/branchCardHelpers.test.ts
@@ -8,6 +8,7 @@ import {
   extractPrNumber,
   extractPrUrl,
   isGitActionInFlight,
+  isImageAttachmentFile,
   isImageFile,
   isMaybeTextFile,
   isPushRejectedNonFastForward,
@@ -62,6 +63,15 @@ describe('file type helpers', () => {
       const filePath = `/tmp/image.${extension}`;
 
       expect(isImageFile(filePath)).toBe(true);
+      expect(isImageAttachmentFile(filePath)).toBe(true);
+      expect(isMaybeTextFile(filePath)).toBe(false);
+    }
+  });
+
+  it('attaches PDFs through the image store rather than reading them as text', () => {
+    for (const filePath of ['/tmp/report.pdf', '/tmp/Scan.PDF']) {
+      expect(isImageFile(filePath)).toBe(false);
+      expect(isImageAttachmentFile(filePath)).toBe(true);
       expect(isMaybeTextFile(filePath)).toBe(false);
     }
   });
@@ -71,6 +81,7 @@ describe('file type helpers', () => {
       const filePath = `/tmp/image.${extension}`;
 
       expect(isImageFile(filePath)).toBe(false);
+      expect(isImageAttachmentFile(filePath)).toBe(false);
       expect(isMaybeTextFile(filePath)).toBe(true);
     }
   });
diff --git a/apps/staged/src/lib/features/branches/branchCardHelpers.ts b/apps/staged/src/lib/features/branches/branchCardHelpers.ts
index e6a739e65..7a5af3a14 100644
--- a/apps/staged/src/lib/features/branches/branchCardHelpers.ts
+++ b/apps/staged/src/lib/features/branches/branchCardHelpers.ts
@@ -3,6 +3,8 @@ import type { PushState } from '../../stores/pushState.svelte';
 import type { PipelineExecution } from '../../types';
 
 const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
+// Stored through the image attachment store too, as a PDF.
+const PDF_EXTENSIONS = ['.pdf'];
 
 /**
  * Whether a push or pull of the branch's own is running or waiting on the branch
@@ -245,8 +247,14 @@ export function isImageFile(filePath: string): boolean {
   return IMAGE_EXTENSIONS.some((ext) => lower.endsWith(ext));
 }
 
+/** Files `createImage` accepts: images plus PDFs, stored as PDFs. */
+export function isImageAttachmentFile(filePath: string): boolean {
+  const lower = filePath.toLowerCase();
+  return isImageFile(filePath) || PDF_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+
 export function isMaybeTextFile(filePath: string): boolean {
-  return !isImageFile(filePath);
+  return !isImageAttachmentFile(filePath);
 }
 
 /**
diff --git a/apps/staged/src/lib/features/sessions/AttachmentThumb.svelte b/apps/staged/src/lib/features/sessions/AttachmentThumb.svelte
new file mode 100644
index 000000000..6df83e49e
--- /dev/null
+++ b/apps/staged/src/lib/features/sessions/AttachmentThumb.svelte
@@ -0,0 +1,92 @@
+<!--
+  AttachmentThumb.svelte — Contents of one chat attachment thumbnail slot
+
+  Fills a positioned, sized parent (composer strip, chat history bubble,
+  queued message) with the attachment's preview: the image itself, or the
+  rendered first page of a PDF with a "PDF" badge. While the preview is
+  loading, or when a PDF could not be rendered, an icon stands in.
+
+  Props:
+    preview  — backend thumbnail; undefined while loading, null when the
+               attachment could not be loaded at all
+    alt      — alt text for the image
+    iconSize — size of the stand-in icon
+    fit      — 'cover' (default) fills the parent's box, cropping the image;
+               'natural' takes the parent's width at the image's own aspect,
+               cropped only past the parent's --attachment-thumb-max-height
+-->
+<script lang="ts">
+  import ImagePlus from '@lucide/svelte/icons/image-plus';
+  import FileText from '@lucide/svelte/icons/file-text';
+  import { isPdfMimeType, type AttachmentPreview } from './attachmentPreview';
+
+  interface Props {
+    preview: AttachmentPreview | null | undefined;
+    alt: string;
+    iconSize?: number;
+    fit?: 'cover' | 'natural';
+  }
+
+  let { preview, alt, iconSize = 16, fit = 'cover' }: Props = $props();
+
+  let isPdf = $derived(!!preview && isPdfMimeType(preview.mimeType));
+  let title = $derived(preview?.filename || undefined);
+</script>
+
+{#if preview?.dataUrl}
+  <img src={preview.dataUrl} {alt} {title} class:natural={fit === 'natural'} />
+{:else}
+  <div class="attachment-thumb-placeholder" class:natural={fit === 'natural'} {title}>
+    {#if isPdf}
+      <FileText size={iconSize} />
+    {:else}
+      <ImagePlus size={iconSize} />
+    {/if}
+  </div>
+{/if}
+{#if isPdf}
+  <span class="attachment-thumb-badge" aria-hidden="true">PDF</span>
+{/if}
+
+<style>
+  img {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+
+  img.natural {
+    height: auto;
+    max-height: var(--attachment-thumb-max-height, none);
+  }
+
+  .attachment-thumb-placeholder {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    color: var(--text-faint);
+  }
+
+  .attachment-thumb-placeholder.natural {
+    height: auto;
+    aspect-ratio: 1;
+  }
+
+  .attachment-thumb-badge {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    padding: 0 3px;
+    border-top-right-radius: 4px;
+    background: var(--bg-deepest);
+    color: var(--text-primary);
+    font-size: 9px;
+    font-weight: 600;
+    line-height: 12px;
+    letter-spacing: 0.02em;
+    pointer-events: none;
+  }
+</style>
diff --git a/apps/staged/src/lib/features/sessions/ChatComposer.svelte b/apps/staged/src/lib/features/sessions/ChatComposer.svelte
index e00dc4ed1..be7c294ac 100644
--- a/apps/staged/src/lib/features/sessions/ChatComposer.svelte
+++ b/apps/staged/src/lib/features/sessions/ChatComposer.svelte
@@ -25,9 +25,11 @@
   import type { Snippet } from 'svelte';
   import X from '@lucide/svelte/icons/x';
   import Paperclip from '@lucide/svelte/icons/paperclip';
-  import ImagePlus from '@lucide/svelte/icons/image-plus';
   import Spinner from '../../shared/Spinner.svelte';
   import { Button } from '$lib/components/ui/button';
+  import { ATTACHMENT_ACCEPT } from './attachErrors';
+  import AttachmentThumb from './AttachmentThumb.svelte';
+  import type { AttachmentPreview } from './attachmentPreview';
   import HashtagInput from './HashtagInput.svelte';
   import type { HashtagItem } from '../../types';
 
@@ -44,8 +46,8 @@
     canAttachImages?: boolean;
     /** IDs of images currently attached to the pending message. */
     attachedImageIds?: string[];
-    /** Image ID → data URL previews for the attached images. */
-    imagePreviews?: Map<string, string>;
+    /** Image ID → preview for the attached images and PDFs (null: failed to load). */
+    imagePreviews?: Map<string, AttachmentPreview | null>;
     onAttachFiles?: (files: File[]) => void;
     onRemoveImage?: (imageId: string) => void;
     /** Why the last attachment was rejected, shown until the next attempt. */
@@ -96,18 +98,14 @@
     <div class="reply-images">
       {#each attachedImageIds as imageId (imageId)}
         <div class="group/thumb reply-image-thumb">
-          {#if imagePreviews.get(imageId)}
-            <img src={imagePreviews.get(imageId)} alt="attached" />
-          {:else}
-            <div class="reply-image-placeholder"><ImagePlus size={16} /></div>
-          {/if}
+          <AttachmentThumb preview={imagePreviews.get(imageId)} alt="attached" />
           {#if !isLive}
             <Button
               variant="ghost"
               size="icon"
               class="reply-image-remove-action absolute top-0.5 right-0.5 size-4 rounded-full bg-[var(--bg-deepest)] text-muted-foreground opacity-0 shadow-none transition-opacity hover:bg-[var(--bg-chrome)] hover:text-foreground group-hover/thumb:opacity-100 [&_svg]:!size-2.5"
-              title="Remove image"
-              aria-label="Remove image"
+              title="Remove attachment"
+              aria-label="Remove attachment"
               onclick={() => onRemoveImage?.(imageId)}
             >
               <X size={10} />
@@ -136,16 +134,16 @@
       <input
         bind:this={fileInputEl}
         type="file"
-        accept="image/png,image/jpeg,image/gif,image/webp,image/svg+xml"
+        accept="{ATTACHMENT_ACCEPT},image/svg+xml"
         multiple
         class="file-input-hidden"
         onchange={handleImageFileSelect}
       />
-      <span class="inline-flex" title="Attach image">
+      <span class="inline-flex" title="Attach image or PDF">
         <Button
           variant="outline"
           class={attachButtonClass}
-          aria-label="Attach image"
+          aria-label="Attach image or PDF"
           onclick={openImagePicker}
           disabled={isLive}
         >
@@ -215,21 +213,6 @@
     flex-shrink: 0;
   }
 
-  .reply-image-thumb img {
-    width: 100%;
-    height: 100%;
-    object-fit: cover;
-  }
-
-  .reply-image-placeholder {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 100%;
-    height: 100%;
-    color: var(--text-faint);
-  }
-
   .reply-image-thumb:focus-within :global(.reply-image-remove-action),
   :global(.reply-image-remove-action:focus-visible) {
     opacity: 1;
diff --git a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
index 8ae84e0fb..5f991c221 100644
--- a/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
+++ b/apps/staged/src/lib/features/sessions/ImageAttachment.svelte
@@ -1,9 +1,10 @@
 <!--
-  ImageAttachment.svelte — Attach images or text snippets to a session prompt
+  ImageAttachment.svelte — Attach images, PDFs, or text snippets to a session prompt
 
   Provides a file picker button, thumbnail previews with remove buttons,
-  and clipboard paste support (Ctrl/Cmd+V). Images are uploaded to the
-  backend as base64-encoded data via the `create_image_from_data` command.
+  and clipboard paste support (Ctrl/Cmd+V). Files are uploaded to the
+  backend as base64-encoded data via the `create_image_from_data` command;
+  a PDF is stored as-is and previewed through its rendered first page.
 
   Text snippets are modal-local (folded into the prompt on submit, never
   persisted): they render as chips alongside the image thumbnails, and an
@@ -28,10 +29,18 @@
   import ClipboardPaste from '@lucide/svelte/icons/clipboard-paste';
   import FileText from '@lucide/svelte/icons/file-text';
   import { Button } from '$lib/components/ui/button';
-  import { createImageFromData, getImageData, deleteImage } from '../../commands';
+  import { createImageFromData, getAttachmentThumbnail, deleteImage } from '../../commands';
   import type { Image } from '../../types';
   import type { TextSnippet } from './sessionModalHelpers';
-  import { attachErrorReason, formatAttachErrors, type AttachRejection } from './attachErrors';
+  import AttachmentThumb from './AttachmentThumb.svelte';
+  import { localPreview, type AttachmentPreview } from './attachmentPreview';
+  import {
+    ATTACHMENT_ACCEPT,
+    attachErrorReason,
+    formatAttachErrors,
+    isAttachableClipboardType,
+    type AttachRejection,
+  } from './attachErrors';
 
   type ImageIdsUpdate = string[] | ((current: string[]) => string[]);
 
@@ -59,24 +68,24 @@
 
   let hasAttachments = $derived(imageIds.length > 0 || textSnippets.length > 0);
 
-  let previews = $state<Map<string, string>>(new Map());
+  // Image ID → preview; null once a load failed, so it is not retried forever.
+  let previews = $state<Map<string, AttachmentPreview | null>>(new Map());
   let attachError = $state<string | null>(null);
   let fileInput: HTMLInputElement;
 
-  // Load previews for existing images
+  // Load previews for existing attachments
   $effect(() => {
     for (const id of imageIds) {
       if (!previews.has(id)) {
-        getImageData(id)
-          .then((dataUrl) => {
+        getAttachmentThumbnail(id)
+          .then((preview) => {
             previews = new Map(previews);
-            previews.set(id, dataUrl);
+            previews.set(id, preview);
           })
           .catch((err) => {
-            console.error('Failed to load image preview:', err);
-            // Insert sentinel to prevent infinite retries
+            console.error('Failed to load attachment preview:', err);
             previews = new Map(previews);
-            previews.set(id, '');
+            previews.set(id, null);
           });
       }
     }
@@ -127,11 +136,14 @@
         true
       );
       onImageIdsChange((current) => [...current, image.id]);
-      // Set preview immediately from the local data. The stored MIME follows
-      // the file signature, which may differ from the browser's label.
-      const dataUrl = `data:${image.mimeType};base64,${base64}`;
-      previews = new Map(previews);
-      previews.set(image.id, dataUrl);
+      // Preview from the local bytes when they can stand in for the stored
+      // file; otherwise (relabelled image, PDF) the effect above fetches the
+      // backend thumbnail.
+      const preview = localPreview(image, file.type, base64);
+      if (preview) {
+        previews = new Map(previews);
+        previews.set(image.id, preview);
+      }
       return null;
     } catch (err) {
       console.error('Failed to attach image:', err);
@@ -145,7 +157,7 @@
     if (!items || disabled) return;
     const files: File[] = [];
     for (const item of Array.from(items)) {
-      if (item.type.startsWith('image/')) {
+      if (isAttachableClipboardType(item.type)) {
         e.preventDefault();
         const file = item.getAsFile();
         if (file) files.push(file);
@@ -169,7 +181,7 @@
 <input
   bind:this={fileInput}
   type="file"
-  accept="image/png,image/jpeg,image/gif,image/webp"
+  accept={ATTACHMENT_ACCEPT}
   multiple
   class="file-input-hidden"
   onchange={handleFileSelect}
@@ -179,18 +191,14 @@
   <div class="attached-images">
     {#each imageIds as imageId}
       <div class="group/thumb image-thumb">
-        {#if previews.get(imageId)}
-          <img src={previews.get(imageId)} alt="attached" />
-        {:else}
-          <div class="image-placeholder"><ImagePlus size={16} /></div>
-        {/if}
+        <AttachmentThumb preview={previews.get(imageId)} alt="attached" />
         {#if !disabled}
           <Button
             variant="ghost"
             size="icon"
             class="image-remove-action absolute top-0.5 right-0.5 size-4 rounded-full bg-[var(--bg-deepest)] text-muted-foreground opacity-0 shadow-none transition-opacity hover:bg-[var(--bg-chrome)] hover:text-foreground group-hover/thumb:opacity-100 [&_svg]:!size-2.5"
-            title="Remove image"
-            aria-label="Remove image"
+            title="Remove attachment"
+            aria-label="Remove attachment"
             onclick={() => removeImage(imageId)}
           >
             <X size={10} />
@@ -221,8 +229,8 @@
         variant="outline"
         size="icon"
         class="size-12 shrink-0 rounded-md border border-dashed border-[var(--border-muted)] bg-transparent text-[var(--text-faint)] shadow-none hover:border-[var(--border-emphasis)] hover:bg-transparent hover:text-muted-foreground [&_svg]:!size-4"
-        title="Add image"
-        aria-label="Add image"
+        title="Add image or PDF"
+        aria-label="Add image or PDF"
         onclick={openFilePicker}
       >
         <Plus size={16} />
@@ -250,7 +258,7 @@
       onclick={openFilePicker}
     >
       <ImagePlus size={14} />
-      <span>Attach images</span>
+      <span>Attach images or PDFs</span>
     </Button>
     {#if onAttachClipboard}
       <Button
@@ -300,12 +308,6 @@
     flex-shrink: 0;
   }
 
-  .image-thumb img {
-    width: 100%;
-    height: 100%;
-    object-fit: cover;
-  }
-
   .image-thumb:focus-within :global(.image-remove-action),
   :global(.image-remove-action:focus-visible) {
     opacity: 1;
@@ -317,15 +319,6 @@
     }
   }
 
-  .image-placeholder {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 100%;
-    height: 100%;
-    color: var(--text-faint);
-  }
-
   .attach-controls {
     display: flex;
     align-items: center;
diff --git a/apps/staged/src/lib/features/sessions/NewSessionModal.svelte b/apps/staged/src/lib/features/sessions/NewSessionModal.svelte
index 95c5b61ae..bf948a307 100644
--- a/apps/staged/src/lib/features/sessions/NewSessionModal.svelte
+++ b/apps/staged/src/lib/features/sessions/NewSessionModal.svelte
@@ -48,7 +48,7 @@
   import { Button } from '$lib/components/ui/button';
   import { subscribeDragDrop } from '../branches/dragDrop';
   import {
-    isImageFile,
+    isImageAttachmentFile,
     isMaybeTextFile,
     insertFilePathsAtCursor,
   } from '../branches/branchCardHelpers';
@@ -480,7 +480,7 @@
 
   async function handleFileDrop(paths: string[]) {
     if (!activeProjectId) return;
-    const imagePaths = paths.filter((p) => isImageFile(p));
+    const imagePaths = paths.filter((p) => isImageAttachmentFile(p));
     const textPaths = paths.filter((p) => isMaybeTextFile(p));
     const newIds: string[] = [];
     for (const path of imagePaths) {
diff --git a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
index 6201e87ae..745ada78f 100644
--- a/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionChatPane.svelte
@@ -41,7 +41,6 @@
   import GitBranch from '@lucide/svelte/icons/git-branch';
   import BookOpen from '@lucide/svelte/icons/book-open';
   import FileText from '@lucide/svelte/icons/file-text';
-  import ImagePlus from '@lucide/svelte/icons/image-plus';
   import Spinner from '../../shared/Spinner.svelte';
   import { isResumableReason } from '../../types';
   import type {
@@ -62,7 +61,7 @@
     createImageFromData,
     deleteImage,
     discoverAcpConfig,
-    getImageData,
+    getAttachmentThumbnail,
     getSession,
     getSessionAcpMetadataMessages,
     getSessionBackgroundHold,
@@ -124,15 +123,18 @@
   import { Button } from '$lib/components/ui/button';
   import { subscribeDragDrop } from '../branches/dragDrop';
   import {
-    isImageFile,
+    isImageAttachmentFile,
     isMaybeTextFile,
     insertFilePathsAtCursor,
   } from '../branches/branchCardHelpers';
   import { hasXmlBlocks, sessionEndMessage, XML_BLOCK_TAGS } from './sessionModalHelpers';
+  import AttachmentThumb from './AttachmentThumb.svelte';
+  import { localPreview, type AttachmentPreview } from './attachmentPreview';
   import {
     attachBasename,
     attachErrorReason,
     formatAttachErrors,
+    isAttachableClipboardType,
     type AttachRejection,
   } from './attachErrors';
   import {
@@ -488,30 +490,31 @@
   // Image attachment state (available when project context is provided; branchId is optional)
   let canAttachImages = $derived(!!projectId);
   let replyImageIds = $state<string[]>([]);
-  let imagePreviews = $state<Map<string, string>>(new Map());
+  // Image ID → preview; null once a load failed, so it is not retried forever.
+  let imagePreviews = $state<Map<string, AttachmentPreview | null>>(new Map());
   let attachError = $state<string | null>(null);
 
   // Drag-and-drop state
   let dragOver = $state(false);
   let modalElement: HTMLElement | null = $state(null);
 
-  // Shared image data cache for both reply previews and message history images.
-  // Maps image ID → data URL. Loaded lazily when needed.
-  let messageImageCache = $state<Map<string, string>>(new Map());
+  // Preview cache for message history and queued-message attachments.
+  // Maps image ID → preview (null: failed). Loaded lazily when needed.
+  let messageImageCache = $state<Map<string, AttachmentPreview | null>>(new Map());
 
-  // Load previews for attached images
+  // Load previews for attached images and PDFs
   $effect(() => {
     for (const id of replyImageIds) {
       if (!imagePreviews.has(id)) {
-        getImageData(id)
-          .then((dataUrl) => {
+        getAttachmentThumbnail(id)
+          .then((preview) => {
             imagePreviews = new Map(imagePreviews);
-            imagePreviews.set(id, dataUrl);
+            imagePreviews.set(id, preview);
           })
           .catch(() => {
-            // Image may have been deleted — insert sentinel to prevent infinite retry
+            // Image may have been deleted
             imagePreviews = new Map(imagePreviews);
-            imagePreviews.set(id, '');
+            imagePreviews.set(id, null);
           });
       }
     }
@@ -534,14 +537,14 @@
     }
     for (const id of allImageIds) {
       if (!messageImageCache.has(id)) {
-        getImageData(id)
-          .then((dataUrl) => {
+        getAttachmentThumbnail(id)
+          .then((preview) => {
             messageImageCache = new Map(messageImageCache);
-            messageImageCache.set(id, dataUrl);
+            messageImageCache.set(id, preview);
           })
           .catch(() => {
             messageImageCache = new Map(messageImageCache);
-            messageImageCache.set(id, '');
+            messageImageCache.set(id, null);
           });
       }
     }
@@ -580,9 +583,14 @@
         true
       );
       replyImageIds = [...replyImageIds, image.id];
-      const dataUrl = `data:${image.mimeType};base64,${base64}`;
-      imagePreviews = new Map(imagePreviews);
-      imagePreviews.set(image.id, dataUrl);
+      // Preview from the local bytes when they can stand in for the stored
+      // file; otherwise (relabelled image, PDF) the effect fetches the
+      // backend thumbnail.
+      const preview = localPreview(image, file.type, base64);
+      if (preview) {
+        imagePreviews = new Map(imagePreviews);
+        imagePreviews.set(image.id, preview);
+      }
       return null;
     } catch (err) {
       console.error('Failed to attach image:', err);
@@ -596,7 +604,7 @@
     if (!items) return;
     const files: File[] = [];
     for (const item of Array.from(items)) {
-      if (item.type.startsWith('image/')) {
+      if (isAttachableClipboardType(item.type)) {
         e.preventDefault();
         const file = item.getAsFile();
         if (file) files.push(file);
@@ -618,7 +626,7 @@
   // Drag-and-drop files (via Tauri native drag-drop events)
   async function handleFileDrop(paths: string[]) {
     if (!projectId) return;
-    const imagePaths = paths.filter((p) => isImageFile(p));
+    const imagePaths = paths.filter((p) => isImageAttachmentFile(p));
     const textPaths = paths.filter((p) => isMaybeTextFile(p));
     const bid = branchId ?? null;
     const pid = projectId;
@@ -2242,17 +2250,13 @@
                     {#if group.message.imageIds && group.message.imageIds.length > 0}
                       <div class="message-images">
                         {#each group.message.imageIds as imgId}
-                          {#if messageImageCache.get(imgId)}
-                            <img
-                              class="message-image-thumb"
-                              src={messageImageCache.get(imgId)}
+                          <div class="message-image-thumb">
+                            <AttachmentThumb
+                              preview={messageImageCache.get(imgId)}
                               alt="attachment"
+                              fit="natural"
                             />
-                          {:else}
-                            <div class="message-image-placeholder">
-                              <ImagePlus size={16} />
-                            </div>
-                          {/if}
+                          </div>
                         {/each}
                       </div>
                     {/if}
@@ -2568,11 +2572,13 @@
                 {#if msg.imageIds.length > 0}
                   <div class="queue-item-images">
                     {#each msg.imageIds as imageId}
-                      {#if messageImageCache.get(imageId)}
-                        <img src={messageImageCache.get(imageId)} alt="queued attachment" />
-                      {:else}
-                        <span class="queue-item-image-placeholder"><ImagePlus size={12} /></span>
-                      {/if}
+                      <span class="queue-item-image">
+                        <AttachmentThumb
+                          preview={messageImageCache.get(imageId)}
+                          alt="queued attachment"
+                          iconSize={12}
+                        />
+                      </span>
                     {/each}
                   </div>
                 {/if}
@@ -2822,25 +2828,15 @@
     margin-top: 6px;
   }
 
+  /* 120px wide at the image's own aspect, cropped only past 120px tall. */
   .message-image-thumb {
+    --attachment-thumb-max-height: 120px;
+    position: relative;
     width: 120px;
-    max-height: 120px;
-    object-fit: cover;
-    border-radius: 8px;
-    border: 1px solid var(--border-subtle);
-    cursor: pointer;
-  }
-
-  .message-image-placeholder {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 48px;
-    height: 48px;
+    overflow: hidden;
     border-radius: 8px;
     border: 1px solid var(--border-subtle);
     background: var(--bg-hover);
-    color: var(--text-faint);
   }
 
   /* Context blocks (action/branch-history tags rendered as tool-call-style cards) */
@@ -3233,23 +3229,14 @@
     flex-wrap: wrap;
   }
 
-  .queue-item-images img,
-  .queue-item-image-placeholder {
+  .queue-item-image {
+    position: relative;
+    display: inline-block;
     width: 28px;
     height: 28px;
+    overflow: hidden;
     border-radius: 6px;
     border: 1px solid var(--border-subtle);
-  }
-
-  .queue-item-images img {
-    object-fit: cover;
-  }
-
-  .queue-item-image-placeholder {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    color: var(--text-faint);
     background: var(--bg-hover);
   }
 
diff --git a/apps/staged/src/lib/features/sessions/attachErrors.test.ts b/apps/staged/src/lib/features/sessions/attachErrors.test.ts
index dc04d52c8..f834c642b 100644
--- a/apps/staged/src/lib/features/sessions/attachErrors.test.ts
+++ b/apps/staged/src/lib/features/sessions/attachErrors.test.ts
@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { attachBasename, attachErrorReason, formatAttachErrors } from './attachErrors';
+import {
+  ATTACHMENT_ACCEPT,
+  attachBasename,
+  attachErrorReason,
+  formatAttachErrors,
+  isAttachableClipboardType,
+} from './attachErrors';
 
 describe('formatAttachErrors', () => {
   it('returns null when nothing was rejected', () => {
@@ -47,3 +53,22 @@ describe('attachBasename', () => {
     expect(attachBasename('three.png')).toBe('three.png');
   });
 });
+
+describe('isAttachableClipboardType', () => {
+  it('accepts images and PDFs through the attachment store', () => {
+    expect(isAttachableClipboardType('image/png')).toBe(true);
+    expect(isAttachableClipboardType('image/webp')).toBe(true);
+    expect(isAttachableClipboardType('application/pdf')).toBe(true);
+  });
+
+  it('ignores other clipboard payloads', () => {
+    expect(isAttachableClipboardType('text/plain')).toBe(false);
+    expect(isAttachableClipboardType('text/html')).toBe(false);
+    expect(isAttachableClipboardType('application/octet-stream')).toBe(false);
+  });
+
+  it('offers the same types in the file picker', () => {
+    expect(ATTACHMENT_ACCEPT.split(',')).toContain('application/pdf');
+    expect(ATTACHMENT_ACCEPT.split(',')).toContain('image/png');
+  });
+});
diff --git a/apps/staged/src/lib/features/sessions/attachErrors.ts b/apps/staged/src/lib/features/sessions/attachErrors.ts
index 60785b143..a6e7e57fa 100644
--- a/apps/staged/src/lib/features/sessions/attachErrors.ts
+++ b/apps/staged/src/lib/features/sessions/attachErrors.ts
@@ -4,6 +4,18 @@ export interface AttachRejection {
   reason: string;
 }
 
+/**
+ * File-picker `accept` list for the image store. A PDF is accepted alongside
+ * images: it is stored as a PDF, previewed through a rendering of its first
+ * page, and opened in the native PDF viewer.
+ */
+export const ATTACHMENT_ACCEPT = 'image/png,image/jpeg,image/gif,image/webp,application/pdf';
+
+/** Whether a pasted clipboard item can be attached through the image store. */
+export function isAttachableClipboardType(type: string): boolean {
+  return type.startsWith('image/') || type === 'application/pdf';
+}
+
 export function attachErrorReason(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
diff --git a/apps/staged/src/lib/features/sessions/attachmentPreview.test.ts b/apps/staged/src/lib/features/sessions/attachmentPreview.test.ts
new file mode 100644
index 000000000..ec6f7a3c2
--- /dev/null
+++ b/apps/staged/src/lib/features/sessions/attachmentPreview.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import type { Image } from '../../types';
+import { isPdfMimeType, localPreview } from './attachmentPreview';
+
+function image(filename: string, mimeType: string): Image {
+  return {
+    id: 'img-1',
+    branchId: null,
+    projectId: 'p',
+    sessionId: 'pending',
+    filename,
+    mimeType,
+    sizeBytes: 3,
+    createdAt: 0,
+  };
+}
+
+describe('localPreview', () => {
+  it('uses the uploaded bytes when the browser label matches the stored image MIME', () => {
+    expect(localPreview(image('shot.png', 'image/png'), 'image/png', 'AAAA')).toEqual({
+      dataUrl: 'data:image/png;base64,AAAA',
+      mimeType: 'image/png',
+      filename: 'shot.png',
+    });
+  });
+
+  it('defers to the backend thumbnail for relabelled files and PDFs', () => {
+    // A WebP saved as .png is stored as image/webp; the label disagrees.
+    expect(localPreview(image('shot.webp', 'image/webp'), 'image/png', 'AAAA')).toBeNull();
+    // PDF bytes are not something an <img> can show.
+    expect(
+      localPreview(image('doc.pdf', 'application/pdf'), 'application/pdf', 'JVBERi0=')
+    ).toBeNull();
+  });
+});
+
+describe('isPdfMimeType', () => {
+  it('recognises only the PDF MIME', () => {
+    expect(isPdfMimeType('application/pdf')).toBe(true);
+    expect(isPdfMimeType('image/png')).toBe(false);
+  });
+});
diff --git a/apps/staged/src/lib/features/sessions/attachmentPreview.ts b/apps/staged/src/lib/features/sessions/attachmentPreview.ts
new file mode 100644
index 000000000..862eed38c
--- /dev/null
+++ b/apps/staged/src/lib/features/sessions/attachmentPreview.ts
@@ -0,0 +1,34 @@
+import type { AttachmentThumbnail, Image } from '../../types';
+
+/**
+ * What a thumbnail slot knows about a chat attachment: the backend's
+ * `get_attachment_thumbnail` reply (an image's own data URL, or a PNG of a
+ * PDF's first page — `dataUrl` is null when a PDF could not be rendered, and
+ * the slot shows a document icon instead).
+ */
+export type AttachmentPreview = AttachmentThumbnail;
+
+export const PDF_MIME_TYPE = 'application/pdf';
+
+export function isPdfMimeType(mimeType: string): boolean {
+  return mimeType === PDF_MIME_TYPE;
+}
+
+/**
+ * Preview built from the bytes just uploaded, when they are what got stored
+ * and an `<img>` can show them. The stored MIME follows the file signature,
+ * which may differ from the browser's label, and a PDF's bytes are not an
+ * image; in both cases the caller fetches the backend thumbnail instead.
+ */
+export function localPreview(
+  image: Image,
+  browserType: string,
+  base64: string
+): AttachmentPreview | null {
+  if (image.mimeType !== browserType || !image.mimeType.startsWith('image/')) return null;
+  return {
+    dataUrl: `data:${image.mimeType};base64,${base64}`,
+    mimeType: image.mimeType,
+    filename: image.filename,
+  };
+}
diff --git a/apps/staged/src/lib/features/timeline/ImageViewerModal.svelte b/apps/staged/src/lib/features/timeline/ImageViewerModal.svelte
index 5e4b56cda..55353e150 100644
--- a/apps/staged/src/lib/features/timeline/ImageViewerModal.svelte
+++ b/apps/staged/src/lib/features/timeline/ImageViewerModal.svelte
@@ -1,8 +1,11 @@
 <!--
-  ImageViewerModal.svelte — Full-size image viewer modal
+  ImageViewerModal.svelte — Full-size attachment viewer modal
 
-  Loads and displays an image by its ID. Supports Escape to close and
-  backdrop click dismissal.
+  Loads and displays an image by its ID, or a PDF attachment in the webview's
+  native PDF viewer (vector zoom, every page) by pointing a full-height frame
+  at the attachment's served media URL, so the viewer streams the file with
+  Range requests instead of the bytes crossing IPC as base64. Supports Escape
+  to close and backdrop click dismissal.
 -->
 <script lang="ts">
   import X from '@lucide/svelte/icons/x';
@@ -13,6 +16,7 @@
   import { viewport } from '../../shared/viewport.svelte';
   import ReferenceNavControls from '../references/ReferenceNavControls.svelte';
   import type { ReferenceNavState } from '../references/referenceHistory.svelte';
+  import { resolvePdfAttachmentUrl } from '../../shared/markdown/mediaUrl';
 
   interface Props {
     open: boolean;
@@ -27,24 +31,52 @@
   let dataUrl = $state<string | null>(null);
   let loading = $state(true);
 
+  // Stored filenames take the extension of the sniffed format, so `.pdf`
+  // means a PDF attachment: shown from its media URL, sized for a document.
+  let isPdf = $derived(/\.pdf$/i.test(filename));
+  let pdfUrl = $derived(isPdf ? resolvePdfAttachmentUrl(imageId) : null);
+
   $effect(() => {
-    if (!open) return;
+    if (!open || isPdf) return;
     loading = true;
     dataUrl = null;
+    let cancelled = false;
     getImageData(imageId)
       .then((url) => {
+        if (cancelled) return;
         dataUrl = url;
         loading = false;
       })
       .catch(() => {
-        loading = false;
+        if (!cancelled) loading = false;
       });
+    return () => {
+      cancelled = true;
+    };
   });
+
+  // Keys pressed inside the PDF frame do not reach the dialog. In Tauri the
+  // frame is another origin (the staged-media scheme), so this listener
+  // cannot attach and the close button and backdrop remain; in web mode the
+  // frame is same-origin and Escape is forwarded where the viewer lets the
+  // frame window see it.
+  function forwardFrameEscape(e: Event) {
+    const frame = e.currentTarget as HTMLIFrameElement;
+    try {
+      frame.contentWindow?.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') onClose();
+      });
+    } catch {
+      // Cross-origin frame: the close button remains.
+    }
+  }
 </script>
 
 <Dialog.Root {open} onOpenChange={(v) => !v && onClose()}>
   <Dialog.Content
-    class="max-w-[90vw] max-h-[90vh] w-auto bg-background p-0 gap-0 overflow-hidden border border-[var(--border-subtle)] flex flex-col"
+    class="max-w-[90vw] sm:max-w-[90vw] max-h-[90vh] bg-background p-0 gap-0 overflow-hidden border border-[var(--border-subtle)] flex flex-col {isPdf
+      ? 'w-[90vw] h-[90vh]'
+      : 'w-auto'}"
     showCloseButton={false}
   >
     <Dialog.Header
@@ -62,8 +94,8 @@
           <Button
             variant="ghost"
             size="icon-sm"
-            title="Delete image"
-            aria-label="Delete image"
+            title="Delete attachment"
+            aria-label="Delete attachment"
             onclick={onDelete}
             class="size-7 shrink-0 text-muted-foreground hover:bg-[var(--bg-hover)] hover:text-destructive [&_svg]:!size-4"
           >
@@ -82,8 +114,11 @@
         </Button>
       </div>
     </Dialog.Header>
-    <div class="modal-body">
-      {#if loading}
+    <div class="modal-body" class:pdf={isPdf}>
+      {#if pdfUrl}
+        <iframe class="pdf-frame" src={pdfUrl} title={filename} onload={forwardFrameEscape}
+        ></iframe>
+      {:else if loading}
         <div class="placeholder">Loading...</div>
       {:else if dataUrl}
         <img src={dataUrl} alt={filename} />
@@ -111,6 +146,12 @@
     min-height: 200px;
   }
 
+  .modal-body.pdf {
+    flex: 1;
+    min-height: 0;
+    padding: 0;
+  }
+
   .modal-body img {
     max-width: 100%;
     max-height: calc(90vh - 80px);
@@ -118,6 +159,14 @@
     border-radius: 4px;
   }
 
+  .pdf-frame {
+    flex: 1;
+    width: 100%;
+    height: 100%;
+    border: 0;
+    background: var(--bg-primary);
+  }
+
   .placeholder {
     font-size: var(--size-sm);
     color: var(--text-muted);
diff --git a/apps/staged/src/lib/shared/markdown/mediaUrl.test.ts b/apps/staged/src/lib/shared/markdown/mediaUrl.test.ts
index c2910365a..3a7a72aa3 100644
--- a/apps/staged/src/lib/shared/markdown/mediaUrl.test.ts
+++ b/apps/staged/src/lib/shared/markdown/mediaUrl.test.ts
@@ -4,8 +4,20 @@ vi.mock('@tauri-apps/api/core', () => ({
   convertFileSrc: vi.fn(() => 'staged-media://localhost/file'),
 }));
 import { convertFileSrc } from '@tauri-apps/api/core';
-import { resolveStagedMediaUrl } from './mediaUrl';
+import {
+  parseStagedMediaReference,
+  resolvePdfAttachmentUrl,
+  resolveStagedMediaUrl,
+} from './mediaUrl';
 it('delegates platform-specific protocol URLs to Tauri', () => {
   expect(resolveStagedMediaUrl('id', 'png')).toBe('staged-media://localhost/file');
   expect(convertFileSrc).toHaveBeenCalledWith('id.png', 'staged-media');
 });
+
+it('resolves PDF attachments by id without admitting them as note embeds', () => {
+  expect(resolvePdfAttachmentUrl('id')).toBe('staged-media://localhost/file');
+  expect(convertFileSrc).toHaveBeenCalledWith('id.pdf', 'staged-media');
+  expect(
+    parseStagedMediaReference('staged-media://0f3b9d2a-1c4e-4a5b-8d6e-7f8091a2b3c4.pdf')
+  ).toBeNull();
+});
diff --git a/apps/staged/src/lib/shared/markdown/mediaUrl.ts b/apps/staged/src/lib/shared/markdown/mediaUrl.ts
index ef94c33c5..68b95a50e 100644
--- a/apps/staged/src/lib/shared/markdown/mediaUrl.ts
+++ b/apps/staged/src/lib/shared/markdown/mediaUrl.ts
@@ -17,3 +17,13 @@ export function parseStagedMediaReference(href: string) {
 export function resolveStagedMediaUrl(id: string, ext: string): string {
   return isTauri ? convertFileSrc(`${id}.${ext}`, 'staged-media') : `/api/media/${id}.${ext}`;
 }
+
+/**
+ * Served URL of a PDF chat attachment, for the viewer's `<iframe>`. Looked up
+ * by id like note media (the same protocol and `/api/media` route, Range and
+ * all), but deliberately not via `parseStagedMediaReference`: PDFs stay out
+ * of note embeds.
+ */
+export function resolvePdfAttachmentUrl(id: string): string {
+  return resolveStagedMediaUrl(id, 'pdf');
+}
diff --git a/apps/staged/src/lib/types.ts b/apps/staged/src/lib/types.ts
index 54fe30542..648718b35 100644
--- a/apps/staged/src/lib/types.ts
+++ b/apps/staged/src/lib/types.ts
@@ -299,6 +299,14 @@ export interface BranchGitState {
   };
 }
 
+/** Reply of `get_attachment_thumbnail`; see `attachmentPreview.ts`. */
+export interface AttachmentThumbnail {
+  /** The image's own data URL, or a PNG of a PDF's first page; null when a PDF could not be rendered. */
+  dataUrl: string | null;
+  mimeType: string;
+  filename: string;
+}
+
 export interface Image {
   id: string;
   branchId: string | null;
diff --git a/crates/acp-client/src/driver.rs b/crates/acp-client/src/driver.rs
index 6feff1af4..d98eba3fc 100644
--- a/crates/acp-client/src/driver.rs
+++ b/crates/acp-client/src/driver.rs
@@ -1025,13 +1025,13 @@ pub trait Store: Send + Sync {
 pub trait AgentDriver {
     /// Run a single turn: send `prompt`, stream results via `writer`.
     ///
-    /// `images` contains `(base64_data, mime_type)` pairs that are sent as
-    /// `ContentBlock::Image` entries alongside the text prompt.
+    /// `images` are sent as `ContentBlock::Image` entries alongside the text
+    /// prompt, each preceded by its label when it has one.
     async fn run(
         &self,
         session_id: &str,
         prompt: &str,
-        images: &[(String, String)],
+        images: &[PromptImage],
         working_dir: &Path,
         store: &Arc<dyn Store>,
         writer: &Arc<dyn MessageWriter>,
@@ -1411,7 +1411,7 @@ type SessionTurnResult = Result<AgentRunOutcome, String>;
 /// A prompt turn queued onto a [`SessionConnection`].
 struct QueuedSessionTurn {
     prompt: String,
-    images: Vec<(String, String)>,
+    images: Vec<PromptImage>,
     /// Resolved by the connection task with the turn's outcome.
     reply: oneshot::Sender<SessionTurnResult>,
 }
@@ -1554,7 +1554,7 @@ impl SessionConnection {
     pub async fn prompt(
         &mut self,
         prompt: &str,
-        images: &[(String, String)],
+        images: &[PromptImage],
     ) -> Result<AgentRunOutcome, String> {
         let (reply_tx, reply_rx) = oneshot::channel();
         let turn = QueuedSessionTurn {
@@ -2038,7 +2038,7 @@ impl AgentDriver for AcpDriver {
         &self,
         session_id: &str,
         prompt: &str,
-        images: &[(String, String)],
+        images: &[PromptImage],
         working_dir: &Path,
         store: &Arc<dyn Store>,
         writer: &Arc<dyn MessageWriter>,
@@ -5327,7 +5327,7 @@ async fn run_prompt_turn(
     our_session_id: &str,
     cancel_token: &CancellationToken,
     prompt: &str,
-    images: &[(String, String)],
+    images: &[PromptImage],
 ) -> Result<AgentRunOutcome, String> {
     let supports_images = setup.agent_capabilities.prompt_capabilities.image;
     if !images.is_empty() && !supports_images {
@@ -6301,23 +6301,55 @@ async fn authenticate_with_explicit_method(
     Ok(())
 }
 
+/// An image attached to a prompt. Only `image/*` data is accepted by the ACP
+/// agents (neither claude-agent-acp nor codex-acp forwards blob resources to
+/// the model), so other attachments are rendered to images before they get
+/// here; `label` carries the caption that says which page of what.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PromptImage {
+    /// Base64 of the image bytes.
+    pub data: String,
+    pub mime_type: String,
+    /// Sent as a text block immediately before the image.
+    pub label: Option<String>,
+}
+
+impl PromptImage {
+    pub fn new(data: impl Into<String>, mime_type: impl Into<String>) -> Self {
+        Self {
+            data: data.into(),
+            mime_type: mime_type.into(),
+            label: None,
+        }
+    }
+
+    pub fn with_label(mut self, label: impl Into<String>) -> Self {
+        self.label = Some(label.into());
+        self
+    }
+}
+
 fn build_prompt_content_blocks(
     prompt: &str,
-    images: &[(String, String)],
+    images: &[PromptImage],
     supports_images: bool,
 ) -> Vec<AcpContentBlock> {
     let mut content_blocks = vec![AcpContentBlock::Text(TextContent::new(prompt))];
 
     if supports_images {
-        for (data, mime_type) in images {
+        for image in images {
+            if let Some(label) = &image.label {
+                content_blocks.push(AcpContentBlock::Text(TextContent::new(label.as_str())));
+            }
             content_blocks.push(AcpContentBlock::Image(ImageContent::new(
-                data.as_str(),
-                mime_type.as_str(),
+                image.data.as_str(),
+                image.mime_type.as_str(),
             )));
         }
     } else if !images.is_empty() {
+        // Blocks, not attachments: one PDF arrives as one image per page.
         content_blocks.push(AcpContentBlock::Text(TextContent::new(format!(
-            "[{} image attachment(s) omitted because this ACP provider does not advertise promptCapabilities.image]",
+            "[{} image block(s) omitted because this ACP provider does not advertise promptCapabilities.image]",
             images.len()
         ))));
     }
@@ -6476,10 +6508,10 @@ mod tests {
         AsyncTaskStopHandle, AsyncTaskUpdate, BackgroundActivity, BackgroundHoldConfig,
         BackgroundHoldObserver, BackgroundHoldStatus, BackgroundHoldTask, BackgroundTaskSet,
         BasicMessageWriter, HoldOutcome, HoldSettle, HoldingState, IncomingSessionUpdate,
-        MessageWriter, OutOfTurnPermissionPolicy, QueuedSessionTurn, RemoteLineOutcome,
-        ReplayBoundary, ReplayBuffer, ReplayEvent, SdkSessionState, SessionLifetime,
-        SessionSettleReason, SessionSettled, StopAsyncTaskRequest, Store, TaskTrackingMode,
-        TypedAsyncTaskSet, ASYNC_TASK_STOP_METHOD, AVAILABILITY_PROBE_SUBTYPE,
+        MessageWriter, OutOfTurnPermissionPolicy, PromptImage, QueuedSessionTurn,
+        RemoteLineOutcome, ReplayBoundary, ReplayBuffer, ReplayEvent, SdkSessionState,
+        SessionLifetime, SessionSettleReason, SessionSettled, StopAsyncTaskRequest, Store,
+        TaskTrackingMode, TypedAsyncTaskSet, ASYNC_TASK_STOP_METHOD, AVAILABILITY_PROBE_SUBTYPE,
         BACKGROUND_CONTINUATION_ORIGIN, BACKGROUND_TASK_SUBTYPES, CLAUDE_SDK_MESSAGE_METHOD,
         CONTINUATION_MESSAGE_ID_PREFIX, ORIGIN_TASK_NAME_MAX_CHARS, PERMISSION_ANNOUNCEMENT_GRACE,
         SESSION_STATE_SUBTYPE, TASK_NOTIFICATION_ORIGIN,
@@ -8210,14 +8242,14 @@ agent: http=false, sse=false). Select a provider that supports MCP over HTTP/SSE
 
     #[test]
     fn image_prompt_blocks_are_omitted_when_unsupported() {
-        let images = vec![("abcd".to_string(), "image/png".to_string())];
+        let images = vec![PromptImage::new("abcd", "image/png")];
         let blocks = build_prompt_content_blocks("inspect this", &images, false);
 
         assert_eq!(blocks.len(), 2);
         assert!(matches!(blocks[0], AcpContentBlock::Text(_)));
         match &blocks[1] {
             AcpContentBlock::Text(text) => {
-                assert!(text.text.contains("image attachment(s) omitted"));
+                assert!(text.text.contains("image block(s) omitted"));
             }
             other => panic!("expected omission notice text block, got {other:?}"),
         }
@@ -8225,7 +8257,7 @@ agent: http=false, sse=false). Select a provider that supports MCP over HTTP/SSE
 
     #[test]
     fn image_prompt_blocks_are_sent_when_supported() {
-        let images = vec![("abcd".to_string(), "image/png".to_string())];
+        let images = vec![PromptImage::new("abcd", "image/png")];
         let blocks = build_prompt_content_blocks("inspect this", &images, true);
 
         assert_eq!(blocks.len(), 2);
@@ -8233,6 +8265,50 @@ agent: http=false, sse=false). Select a provider that supports MCP over HTTP/SSE
         assert!(matches!(blocks[1], AcpContentBlock::Image(_)));
     }
 
+    #[test]
+    fn labelled_image_prompt_blocks_carry_their_caption_first() {
+        let images = vec![
+            PromptImage::new("abcd", "image/png").with_label("page 1 of 2 of report.pdf"),
+            PromptImage::new("efgh", "image/png").with_label("page 2 of 2 of report.pdf"),
+            PromptImage::new("ijkl", "image/png"),
+        ];
+        let blocks = build_prompt_content_blocks("inspect this", &images, true);
+
+        let shape: Vec<&str> = blocks
+            .iter()
+            .map(|block| match block {
+                AcpContentBlock::Text(text) => text.text.as_str(),
+                AcpContentBlock::Image(_) => "<image>",
+                other => panic!("unexpected block {other:?}"),
+            })
+            .collect();
+        assert_eq!(
+            shape,
+            [
+                "inspect this",
+                "page 1 of 2 of report.pdf",
+                "<image>",
+                "page 2 of 2 of report.pdf",
+                "<image>",
+                "<image>",
+            ]
+        );
+
+        // Without image support the captions go too; only the notice remains.
+        let blocks = build_prompt_content_blocks("inspect this", &images, false);
+        assert_eq!(blocks.len(), 2);
+        match &blocks[1] {
+            AcpContentBlock::Text(text) => {
+                assert!(
+                    text.text.contains("3 image block(s) omitted"),
+                    "{}",
+                    text.text
+                );
+            }
+            other => panic!("expected omission notice text block, got {other:?}"),
+        }
+    }
+
     #[test]
     fn shell_quote_simple_value() {
         assert_eq!(
diff --git a/crates/acp-client/src/lib.rs b/crates/acp-client/src/lib.rs
index 990bc34a8..f2084d29a 100644
--- a/crates/acp-client/src/lib.rs
+++ b/crates/acp-client/src/lib.rs
@@ -35,7 +35,7 @@ pub use driver::{
     AcpPermissionRequest, AcpSessionConfigOptionSelection, AcpToolCallMetadata, AgentDriver,
     AgentRunOutcome, AsyncTaskStopHandle, BackgroundHoldConfig, BackgroundHoldObserver,
     BackgroundHoldStatus, BackgroundHoldTask, BasicMessageWriter, MessageWriter,
-    OutOfTurnPermissionPolicy, ReplayBoundary, SessionConnection, SessionLifetime,
+    OutOfTurnPermissionPolicy, PromptImage, ReplayBoundary, SessionConnection, SessionLifetime,
     SessionSettleReason, SessionSettled, Store, BACKGROUND_CONTINUATION_ORIGIN,
 };
 pub use simple::{run_acp_prompt, run_acp_prompt_with_interpreter_env_snapshot};
diff --git a/crates/acp-client/src/simple.rs b/crates/acp-client/src/simple.rs
index 17675f75f..b87b069bc 100644
--- a/crates/acp-client/src/simple.rs
+++ b/crates/acp-client/src/simple.rs
@@ -51,7 +51,7 @@ impl AgentDriver for SimpleDriverWrapper {
         &self,
         session_id: &str,
         prompt: &str,
-        images: &[(String, String)],
+        images: &[crate::driver::PromptImage],
         working_dir: &Path,
         store: &Arc<dyn crate::driver::Store>,
         writer: &Arc<dyn MessageWriter>,