Your Screenshots Are Invisible to a Text-Only AI — Alt-Text as a Vault Discipline

You saved the screenshot, so you assume your AI can see it. A text-only retriever cannot. It reads text, and a binary image file is opaque to it. The low-tech remedy is old: write a real description in the alt slot, and a caption line beside every image.

The accessibility world settled this argument twenty years ago. WebAIM defines alternative text as "a textual substitute for non-text content in web pages"¹, a sentence that stands in for a picture when the picture cannot be perceived. The Web Content Accessibility Guidelines make it normative: under Success Criterion 1.1.1, all non-text content must have "a text alternative that serves the equivalent purpose, except for the situations listed below", a Level A requirement in the 2.2 Recommendation published 12 December 2024.² The point then was a blind reader using a screen reader. The mechanism is identical for a machine that reads text and not pixels. A retriever running over your notes is, functionally, a reader without eyes, and the alt slot was built for exactly that reader — it simply arrived a decade before the reader did.

The assumption: your AI sees the whole vault

Most people trust the vault they built. You clipped the architecture diagram, saved the receipt, screenshotted the error, and filed each one where you would find it again. So when the assistant runs over that folder, the reasonable assumption follows: it reads what you can read. Every note, every picture.

The belief is reasonable, and mostly it holds. Your Markdown is text. Your headings, your links, your prose — a retriever reads all of it, and how you structure a note shapes what it retrieves. The blind spot is not the note. It is one modality inside the note, sitting in plain view.

Images are the exception you stopped noticing.

Why a text-only retriever can't see your screenshots

A local retrieval pipeline usually indexes text. It embeds your Markdown, splits it into chunks, and searches those chunks. An image is a binary file the index never opens — ![](attachments/q3-diagram.png) with an empty alt slot is, to that pipeline, a filename and nothing more. The pixels are unreachable.

In Markdown, an image is written ![alt text](path). The CommonMark specification is precise about that first field: "Instead of link text, we have an image description," and "when an image is rendered to HTML, this is standardly used as the image's alt attribute."³ The description is text. It sits in your file. A text pipeline can index it. Leave it empty and there is nothing to index but a path the retriever has no reason to read.

A saved PDF is the same story — bytes an index skips unless a step extracts and describes them. This is the crack that opens the moment you add an image to a portable Markdown note: the text travels, the picture's meaning does not.

Empty alt text is a silent hole in the index.

The fix is the accessibility discipline you already know

The remedy predates AI by two decades. Web accessibility solved the same problem: describe non-text content in text, so a reader who cannot see the pixels still gets the meaning. WCAG calls it a text alternative. The screen reader and the text retriever want the identical thing — a sentence.

WebAIM's rule for a good alternative is that it "be accurate and equivalent in representing content and function."¹ Write the diagram's actual claim, not "diagram.png". That equivalent sentence is what the retriever indexes, ranks, and quotes back to you when you ask.

The analogy to how retrieval systems already work is exact. Anthropic's Contextual Retrieval technique "solves this problem by prepending chunk-specific explanatory context to each chunk before embedding,"⁴ and reports that the added context reduced the top-20-chunk retrieval failure rate by 35% (49% combined with a keyword search, 67% with reranking).⁴ Your caption is that context, written by hand, for an image. The alt-text is the chunk-context for a picture.

Describe the picture, and the picture joins the index.

What alt-text does not do

Be honest about what a caption fixes and what it does not. Alt-text does not give a text-only pipeline eyes; it hands that pipeline a sentence it can already read. A true multimodal model can read the pixels — when the image reaches it. Whether it reaches it is a separate question, and often the answer is no.

Modern models can see. Anthropic's vision documentation lists the supported formats plainly: "Claude supports JPEG, PNG, GIF, and WebP images."⁵ Simon Willison marked the shift back in 2023, describing "the new mode of GPT-4 that allows you to upload images as part of your conversations."⁶ The pixels are legible to a multimodal model. So why write anything at all?

Three reasons, and none of them expire. First, the retrieval step: many local and text-only stacks never send the image to a vision model, so the picture is invisible before any model with eyes is involved. Second, even a vision model leans on the words around the image; Anthropic notes it "does not parse or receive any metadata from images,"⁵ so the caption you write, not the file's hidden fields, carries the context. Third, vision is not magic: the same docs warn a model "might hallucinate or make mistakes when interpreting low-quality, rotated, or very small images under 200 pixels."⁵

So say it plainly: a caption is not a substitute for a genuine multimodal pipeline. It is the low-tech remedy that makes an image describable to the text retriever you already have. The specific tools that need it will drift — Claude "is an image understanding model only," by its own documentation,⁵ capable today and differently capable next year. The discipline is durable precisely because it does not depend on which model ships next. A sentence describing the image is legible to every reader: human or machine, text-only or multimodal.

Alt-text is the low-tech floor, not the ceiling.

What to do this week

Start with one audit and one habit. Count the binary attachments already in your vault, then decide the ones worth describing. From today, never drop an image without a real alt description and a caption line beneath it. The description is the durable artifact; the image is the illustration.

Begin with the audit. Count what is invisible before you decide what to fix:

find ~/notes -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.pdf' \) | wc -l

POSIX standardises find, its -name primary (which matches the last component of the pathname), and -type.⁷ The case-insensitive -iname used above is a GNU/BSD extension, not part of POSIX — it runs on macOS and Linux, and the parentheses group the alternatives so the count comes out right. The number it prints is the size of your blind spot.

Then the habit. Simon Willison, auditing his own site, wrote: "I got curious today about how I'd been using alt text for images on my blog."⁸ Run the same curiosity over your vault:

1. Describe, don't label. Write what the image shows and why it is filed — "Q3 revenue by region, EU flat" beats "chart.png".
2. Add a caption line beneath the image. A plain sentence under ![...](...) is text the retriever indexes even when the alt slot is stripped on render.
3. Fix the highest-value images first. Whiteboard photos, receipts, architecture diagrams — the ones you will ask about later.
4. Describe at capture time. The thirty seconds when you save the screenshot is the only moment you still remember what it meant.
5. Re-audit after a bulk import. A folder of freshly clipped PDFs is a new crop of invisible files.

This is the fix. To find what is still invisible before you trust an answer, the companion piece turns it into a runnable smoke test: ask your AI what it can't read, and you decide from the result, not the assumption. It pairs with the read-side habit of knowing which files your AI actually read in the first place.

Describe once; find it forever.

Frequently asked questions

How do I make screenshots and images in my Markdown vault searchable by a local AI?

Write a real alt description and a caption line beside each image. A text-only retriever indexes that text; it cannot open the image itself. Describe what the picture shows and why you saved it, and the retriever can find and quote it later.

Why doesn't my local RAG see the PDFs I saved?

Because a text-only pipeline embeds text and skips binary files. A saved PDF is bytes the index never reads unless a step extracts or describes its contents. Until then the PDF is present in the folder but absent from the search — filed, yet unfindable.

Can ChatGPT or Claude read images?

Yes. Vision models accept common formats: Anthropic's documentation lists JPEG, PNG, GIF, and WebP.⁵ But only if your retrieval step actually sends the image to the model. Many local stacks are text-only and never do, so the picture stays invisible regardless of how capable the model is.

What is alt text and why does it matter for AI?

Alt text is a written substitute for an image — WebAIM calls it "a textual substitute for non-text content."¹ It was built for screen readers, but the same sentence lets any text-only reader, a retriever included, know what the picture contains without ever seeing it.

Does writing alt text help SEO or AI ranking?

Treat that as the wrong reason. The durable payoff is describability: a text reader can only work with text you actually wrote. Write the description because it makes the image findable and quotable by any reader — not as a ranking trick, which ages badly and never survived scrutiny.

How do I count all the images in a folder?

Run find ~/notes -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.pdf' \) | wc -l. POSIX defines find, -name, and -type;⁷ the -iname case-insensitive match is a GNU/BSD extension that works on macOS and Linux. The count is the size of your blind spot.

A picture is worth a thousand words to a reader who can see it, and nothing to a reader who cannot. The retriever running over your notes is the second reader. Write the sentence it needs, and the screenshot rejoins the vault it was filed in all along.

Your notes and their images live on your own device as plain Markdown files you control, so the description you write travels beside the picture — mnmnote.com keeps that habit yours.