CortexLM · echobt · Sep 17, 2026 · Sep 17, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -24,5 +24,6 @@ jobs:
       - run: bash scripts/tests/check-docs-site.test.sh
       - run: bash scripts/tests/check-docs-content.test.sh
       - run: node scripts/tests/docs-ui.test.mjs
+      - run: node scripts/tests/docs-images.test.mjs
       - name: Validate the Mintlify build
         run: npm exec --yes --package=mint@4.2.876 -- mint validate
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,10 +11,20 @@ repository root. Preview and validation commands are in `README.md`.
   session or token internals, credentials, private API routes, infrastructure
   details, vendor names, or backend operator runbooks. Competitor product
   names never appear in copy, titles, or `docs.json`.
-- The site carries **no images**. Every page has an `icon` in its frontmatter
-  and every `<Card>` has an `icon`; icons are Font Awesome names (the Mintlify
-  starter default, so `icons.library` stays unset). Do not add `<img>`,
-  `<Frame>`, markdown images, or an `image:` field.
+- Product screenshots are welcome: use actual Cortex interface captures from
+  Paper, composed with Higgsfield wallpaper, not generated or invented UI.
+  Keep readable controls, honest feature states, and no private data.
+  Store exported WebP, PNG or JPG files locally in `images/product/`.
+  Use self-closing `<img src="/images/product/slug-light.webp" alt="..." />`
+  with descriptive, nonempty English alt text and intrinsic width and height.
+  `<Frame>` wrappers are allowed. Put `className="block dark:hidden"` and
+  `className="hidden dark:block"` on enclosing `div` elements, only for actual
+  matching light/dark captures, so hidden zoom controls are not focusable.
+  Follow `design/docs-images.json`; never publish a `galleryOnly` preview.
+  No remote media, tracking pixels, data URLs, unsafe paths, dynamic image
+  attributes, markdown images or `image:` frontmatter. See README for examples.
+  Every page still has a frontmatter `icon` and every `<Card>` an `icon`;
+  icons are Font Awesome names (the starter default; `icons.library` stays unset).
 - Navigation is `navigation.tabs`: one tab per application (Get started, Chat,
   Code, Bot, CLI, Design, Security, Reference), each tab a list of groups, each
   tab and group with an icon. Every product tab opens on its hub page
@@ -28,8 +38,11 @@ repository root. Preview and validation commands are in `README.md`.
 - Only document API paths on `reference/errors`, `bounty/public-api`, and the
   problem pages, and only paths the backend router registers.
 - Run `node scripts/check-docs-site.mjs`,
+  `node scripts/check-docs-content.mjs`,
   `bash scripts/tests/check-docs-site.test.sh`,
-  `node scripts/tests/docs-ui.test.mjs`, then
+  `bash scripts/tests/check-docs-content.test.sh`,
+  `node scripts/tests/docs-ui.test.mjs`,
+  `node scripts/tests/docs-images.test.mjs`, then
   `npm exec --yes --package=mint@4.2.876 -- mint validate` before committing.
 - For error-code or endpoint changes, also run the checker with a backend
   checkout as its first argument. Coordinate the two PRs; the backend owns the

diff --git a/README.md b/README.md
@@ -57,15 +57,64 @@ otherwise collide (`Sessions` in Code and in the CLI, `Skills` in Chat, Bot,
 and the CLI) the title carries the product and `sidebarTitle` keeps the
 sidebar short.
 
-The site has **no images**. Every visual is an icon (Font Awesome, the Mintlify
-starter default).
+Navigation cards and page frontmatter keep their Font Awesome icons (the
+Mintlify starter default). Article bodies may also carry product screenshots.
+
+## Product screenshots
+
+Use actual Cortex interfaces captured from Paper and composed with Higgsfield
+wallpaper. Do not generate or invent interface controls, imply an unavailable
+feature is working, or expose personal data or credentials. Keep the interface
+readable and place each screenshot beside the section it explains; reuse a
+canonical view instead of repeating near-identical visuals across guides.
+
+Commit exports under `images/product/` as WebP, PNG or JPG (`.jpeg` also works).
+Use root-relative URLs and literal, quoted attributes on self-closing `<img />`
+tags. Every image needs descriptive, nonempty English alt text. Include its
+intrinsic width and height to reserve space while it loads. `<Frame>` may wrap
+an image and provide a caption:
+
+```mdx
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-home-light.webp" alt="Cortex Chat home with its composer and workspace navigation." width="3360" height="2240" loading="lazy" />
+</Frame>
+```
+
+Only use theme switching when both files are actual matching captures:
+
+```mdx
+<Frame caption="Interface preview">
+  <div className="block dark:hidden">
+    <img src="/images/product/chat-home-light.webp" alt="Cortex Chat home with its composer and workspace navigation." width="3360" height="2240" loading="lazy" />
+  </div>
+  <div className="hidden dark:block">
+    <img src="/images/product/chat-home-dark.webp" alt="Cortex Chat home with its composer and workspace navigation." width="3360" height="2240" loading="lazy" />
+  </div>
+</Frame>
+```
+
+The checkers require existing, nonempty local files and reject path traversal,
+symlink escapes, URL encoding, queries, fragments, remote URLs and data URLs.
+Image attributes are limited to `src`, `alt`, `width`, `height`, `className`,
+`loading`, `decoding` and `title`; expressions, spreads, event handlers and
+`srcSet` are not supported. Markdown images, `image:` frontmatter and other
+media embeds are not supported; use the checked `<img />` form instead.
+Examples inside code spans, fenced blocks and comments are not rendered images.
+The shared syntax checks do not require a manifest. The provenance regression
+test additionally checks this gallery against `design/docs-images.json`, rejects
+`galleryOnly` assets, and catches unused public exports. See
+[`design/docs-images.md`](design/docs-images.md) for the composition and
+publication policy.
 
 ## Checks
 
 ```bash
 node scripts/check-docs-site.mjs
+node scripts/check-docs-content.mjs
 bash scripts/tests/check-docs-site.test.sh
+bash scripts/tests/check-docs-content.test.sh
 node scripts/tests/docs-ui.test.mjs
+node scripts/tests/docs-images.test.mjs
 npm exec --yes --package=mint@4.2.876 -- mint validate
 ```
 
@@ -88,7 +137,8 @@ that adds the code. The full check fails when:
 - an `ErrorCode` is missing its `/problems/{code}` page, or a page documents a code the API does not emit
 - a `docs.json` navigation slug, group root, navbar or footer href, redirect destination, or internal link has no matching MDX page
 - a documented `/v1/…` path is not registered in `crates/cortex-api/src/router.rs`
-- a page carries an image, lacks a title, description, or icon, repeats another page's title, or has a description over 160 characters
+- a screenshot lacks alt text, references a missing or unsafe local file, uses an unsupported format or embeds remote media
+- a page lacks a title, description, or icon, repeats another page's title, or has a description over 160 characters
 - navigation is not `navigation.tabs` with a tab for each of Chat, Code, Bot, CLI, Design, and Security, each tab and group carrying an icon
 - public MDX documents `/auth/`, `/oauth/`, `refresh_token`, the identity vendor, or the session cookie
 - `api/authentication.mdx` or `api/oauth.mdx` exist, or the navigation lists them

diff --git a/bot/approvals.mdx b/bot/approvals.mdx
@@ -8,6 +8,10 @@ A bot can act on its own computer and in the apps you connected to it, so it ask
 
 This page covers the three choices, which tools always ask and which never do, the automatic policy that decides before you are involved, where pending approvals show up, and what happens when something cannot be settled. **Cortex Bot** is the only Cortex product with per-tool approval, because a bot runs without a round limit and with a machine of its own.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/bot-approvals-light.webp" alt="The Bot approvals inbox with pending tool requests, command context, and allow or deny controls." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## The three choices
 
 One sentence from the product carries the whole model: `Allow runs the parked tool. Deny does not. Always writes a rule.`

diff --git a/bot/computer.mdx b/bot/computer.mdx
@@ -52,6 +52,10 @@ The desktop has one writer at a time. **Take control** hands the mouse and keybo
 
 Taking control is the right move when the bot is stuck on something only you can do, such as a screen it should not be clicking through on its own. For a password, a one-time code or a captcha, do not type it into the thread: the bot raises **Cortex needs you** and the value you enter there is delivered to the computer rather than posted as a message.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/bot-takeover-en-light.webp" alt="The Bot workspace during a computer takeover, with the bot paused and a control for handing the desktop back." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Record a session
 
 The **Videos** tab is the bot's **Recordings** list. A recording captures the full screen, the path the pointer took and zooms on its clicks, which makes it the clearest way to review what a routine did overnight.

diff --git a/bot/conversations.mdx b/bot/conversations.mdx
@@ -40,6 +40,10 @@ The absence of chatter is not the bot being stuck. To watch the detail of a job,
 
 Three things stop a turn and wait. All three appear in the thread, and the first two also block the composer until they are settled, so you cannot talk past a question the bot is holding.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/bot-attention-light.webp" alt="A Bot conversation waiting for help with a sign-in challenge, with an attention request and a take-over control." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 <AccordionGroup>
   <Accordion title="A question" icon="circle-question">
     An `ask_user` call renders a question widget with **Reply** or **Confirm**, and short **Allow**, **Deny**, **Cancel** or **Dismiss** actions where the question is a yes or no. Answered questions are marked `Replied`; one you waved off is marked `dismissed`.

diff --git a/bot/index.mdx b/bot/index.mdx
@@ -10,6 +10,10 @@ A bot is persistent. It keeps its name, its look, its memory, its skills, its ro
 
 This page is the map of the Bot documentation. Start with the quickstart if you have never made a bot, or go straight to the guide you need.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/bot-workspace-en-light.webp" alt="A Bot workspace with an ongoing conversation, an approval request, and the bot's Cloud computer preview." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Start here
 
 <CardGroup cols={2}>

diff --git a/chat/attachments.mdx b/chat/attachments.mdx
@@ -8,6 +8,10 @@ You can send a file along with a message in Cortex Chat. Pick it from your compu
 
 This page covers how to attach a file, what Chat accepts, the size ceiling and where it is enforced, what Cortex can read out of a document, and the messages you see when an upload or an extraction does not work.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-attachments-light.webp" alt="The Chat composer with file attachments and options for choosing files to send with a message." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Attach a file
 
 <Steps>

diff --git a/chat/canvases.mdx b/chat/canvases.mdx
@@ -8,6 +8,10 @@ A Chat canvas is a plain document that opens in a rail beside a conversation. Co
 
 This page covers how to open a canvas, how it saves itself, how to ask Cortex to rewrite part of it, how a canvas differs from a plan, a Library note, a Code file and a Design canvas, and what to do when the rail will not open or save.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-canvas-light.webp" alt="An editable document canvas beside a Chat conversation, with a passage selected for rewriting." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Open a canvas
 
 <Steps>

diff --git a/chat/conversations.mdx b/chat/conversations.mdx
@@ -41,6 +41,10 @@ When standing instructions are in play, the composer shows **Custom instructions
 
 Nothing in a conversation is destroyed by changing your mind. Messages form a tree, and both controls below add a path rather than overwrite one.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-editing-light.webp" alt="A Chat message being edited beside an answer version pager and message actions." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 <Steps>
   <Step title="Edit a message you already sent">
     Hover your own message and choose edit. The banner reads **Editing · original kept as Branch 1**. Change the text and press **Send as branch**, or **Cancel**.

diff --git a/chat/deep-research.mdx b/chat/deep-research.mdx
@@ -45,6 +45,10 @@ When a run was scoped, the report tells the reader: `Citations are shown only wh
 
 Progress is a short status line, not a wall of tool rows. **Research progress** moves through `Queued`, `Searching`, `Reading`, and then `Done` or `Failed`, and the line beside it uses a small fixed vocabulary: `Planning the research`, `Searching the web`, `Reading sources`, `Checking {topic}`, `Filling gaps`, `Writing the report`, `Checking connected apps`. The eyebrow above the block reads `Deep Research · Running`.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/research-running-light.webp" alt="An active Deep Research run showing progress across its research questions and the sources found." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 Two controls are yours while it works:
 
 - **Stop** ends the run.
@@ -58,6 +62,15 @@ The finished report is ordinary Chat text with **numbered citations**, under the
 
 **Open reader** opens the report on its own, away from the thread, and **Follow up** takes you straight back into the chat with it in hand. **Close report** returns you to the conversation.
 
+<Frame caption="Interface preview">
+  <div className="block dark:hidden">
+    <img src="/images/product/research-report-light.webp" alt="A completed Deep Research report in the reader with numbered citations, an outline, and a source sidebar." width="3360" height="2240" loading="lazy" />
+  </div>
+  <div className="hidden dark:block">
+    <img src="/images/product/research-report-dark.webp" alt="A completed Deep Research report in the reader with numbered citations, an outline, and a source sidebar." width="3360" height="2240" loading="lazy" />
+  </div>
+</Frame>
+
 Where a run cited nothing you see `No sources were cited.` or `No sources recorded for this report.` rather than an invented list.
 
 ## Save the report as a file

diff --git a/chat/document-export.mdx b/chat/document-export.mdx
@@ -12,6 +12,10 @@ This page covers the deck export a chat offers and the two ways into it, the pla
 From an ordinary answer, a deck is the only file a chat produces. Other document formats appear only on a Deep Research report card, where Markdown is the one implemented today. There is also no control anywhere in the app that exports a whole conversation as a document.
 </Note>
 
+<Frame caption="Interface preview">
+  <img src="/images/product/document-export-light.webp" alt="A Chat answer beside a deck export panel with a slide outline to review before creating the file." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Export happens in two steps
 
 Nothing is written until the second step, and the split matters for your allowance.

diff --git a/chat/how-it-works.mdx b/chat/how-it-works.mdx
@@ -8,6 +8,10 @@ A **turn** is one message from you plus everything Cortex does to answer it. Ins
 
 This page is for readers who want to know what is actually happening between pressing Enter and reading an answer: what goes into a turn, in what order, what is kept afterwards, and what happens when a conversation grows too long to send.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-citations-light.webp" alt="A cited Chat answer with a footnote source panel open beside the conversation." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## What goes into a turn
 
 | Input | Where it comes from |

diff --git a/chat/image-generation.mdx b/chat/image-generation.mdx
@@ -8,6 +8,10 @@ Ask **Cortex Chat** for a picture in plain language and it writes the picture pr
 
 This page covers asking for a picture, reading the card, steering the size and the seed, where the finished file lands, how many images each plan includes per day, and the cases where nothing runs at all.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-image-result-light.webp" alt="A generated image displayed as a result in a Cortex Chat conversation." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Ask for a picture
 
 <Steps>

diff --git a/chat/index.mdx b/chat/index.mdx
@@ -8,6 +8,15 @@ Cortex Chat is the conversation product at [cortex.foundation](https://cortex.fo
 
 Chat works before you sign in, with a smaller allowance and without uploads, projects or web search. This page describes the surface you land on, then links to every other page in the Chat tab.
 
+<Frame caption="Interface preview">
+  <div className="block dark:hidden">
+    <img src="/images/product/chat-home-light.webp" alt="Cortex Chat home with a message composer, starting prompts, and workspace navigation." width="3360" height="2240" loading="lazy" />
+  </div>
+  <div className="hidden dark:block">
+    <img src="/images/product/chat-home-dark.webp" alt="Cortex Chat home with a message composer, starting prompts, and workspace navigation." width="3360" height="2240" loading="lazy" />
+  </div>
+</Frame>
+
 ## The page you land on
 
 The home page greets you with **Good morning**, **Good afternoon** or **Good evening**, and shows a short list of starting points under the heading **Things Cortex does well.**

diff --git a/chat/library.mdx b/chat/library.mdx
@@ -9,6 +9,15 @@ keywords: ["Artifacts"]
 
 This page covers how files arrive, how to find one, what the row actions do, how versions and **Restore** work, how pinning and the storage allowance behave, and how a file gets back into a chat. Sharing a file and connecting a drive have their own page, [Sharing files and connected drives](/chat/library-sharing).
 
+<Frame caption="Interface preview">
+  <div className="block dark:hidden">
+    <img src="/images/product/library-files-light.webp" alt="The Library grid with document, deck, spreadsheet, and image previews alongside search and file-type filters." width="3360" height="2240" loading="lazy" />
+  </div>
+  <div className="hidden dark:block">
+    <img src="/images/product/library-files-dark.webp" alt="The Library grid with document, deck, spreadsheet, and image previews alongside search and file-type filters." width="3360" height="2240" loading="lazy" />
+  </div>
+</Frame>
+
 ## How files arrive
 
 | Source | Badge | What it is |

diff --git a/chat/memory.mdx b/chat/memory.mdx
@@ -8,6 +8,10 @@ icon: "lightbulb"
 
 Memory is on by default, and everything about it is inspectable. This page covers where to manage it, what it stores, how long it is kept, how to review and delete entries, how to narrow memory to one project, how export and import work, and the cases where memory deliberately does nothing.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-memory-light.webp" alt="Chat memory settings with saved entries, search and category filters, and a memory being edited." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## Where to manage memory
 
 Everything below lives in **Settings → Data & privacy**, under **Memory**. The same panel carries the master switch, the sensitive-topics switch, the retention row, the searchable list of entries, and the export and import controls. The project-scope choice is the one part that lives elsewhere: it is inside each project, under its own **Memory** block. See [Projects](/chat/projects) and [Data and privacy](/getting-started/data-and-privacy).

diff --git a/chat/models.mdx b/chat/models.mdx
@@ -8,6 +8,10 @@ Every conversation in Cortex Chat runs on one model, and the chip under the comp
 
 This page covers the two models Chat publishes today, what the **PREVIEW** badge on them means, how the model and the thinking level are decided, and what Chat tells you when a model is busy or cannot be reached.
 
+<Frame caption="Interface preview">
+  <img src="/images/product/chat-model-picker-light.webp" alt="The Cortex Chat model picker open above the composer with model choices and thinking controls." width="3360" height="2240" loading="lazy" />
+</Frame>
+
 ## The two models
 
 The list in the panel is fetched from Cortex when the page loads rather than built into the app, so it always reflects what your account can actually use. Today it holds two entries, and both are marked Preview.