009 · Files and screenshots

A specification, an implementation plan, and the implementation: give the agent the bytes the user is already holding — by paste, drop, or picker — without ever breaking the fence, the limits, or the transcript's honesty.

Status: specification complete; implementation in progress. 9 November 2026. Scope: the composer's attach surface (web/src/components/Composer.tsx and its neighbourhood), a new blob stage in the API (api/domain/blob.py, api/services/blobs.py, api/adapters/blob/), three routes, one context branch, one MCP tool, and one event type. It changes no existing attachment behaviour: the five reference kinds work exactly as they do today. Relation to earlier specs: extends the context model of 006 · On par with Genie Code and the shell of 007 · The shell, the keys, and the scroll. It reuses 007's audits (a11y, overflow, CLS) as its definition of "not clunky". It does not touch 008 · the public site. Audience: product, full-stack, database, UX/UI, front-end, growth.

The one sentence

A user presses ⌘V with a screenshot on the clipboard, a chip appears in the same frame, and by the time they have typed their question the agent can see what they are looking at — and if it cannot, it says so in one sentence that names the limit.

Everything in this folder is an argument about that sentence.

Read in this order

Cross-reference convention: a requirement is cited as [AFC-3], a decision [D5], an edge case [E-11], a scene [S2], a first principle [P1], a veto [V4]. Every id is defined exactly once — in 03, 07, 09, 01, or 06 — and linked from everywhere else.

The problem

The composer can attach five kinds of thing, and all five are references to workspace objects:

KINDS = ("notebook", "file", "folder", "table", "cell")

That is a good design with one consequence: anything that is not already in the workspace cannot be attached at all. A screenshot on the clipboard, a CSV from a colleague's message, a diagram exported from a design tool — none of these are workspace paths, so there is no chip, no picker, and no wire field for them.

The security rule that produced this is worth keeping:

"Attachments are references (kind + path); the server re-reads the object with the user's own token. The browser never supplies content, so it cannot attach something it cannot read."

The feature is therefore not "add an upload button". It is: let the browser supply content through the same fence, limits, validation, and audit trail that every other write uses — which is P1.

The shape of the answer

  clipboard / drag / picker
        │
        ▼  bytes (validated twice: client courtesy, server rule)
  ┌──────────────┐
  │  BlobStore   │  durable, addressable, swept, never in the event log
  └──────┬───────┘
         │  {kind:"blob", ref:"blb_7f3a"}
         ▼
  turn.attachments ──▶ context.render() ──▶ the model
         │                                    │
         │                                    └── dbx_read_blob for the rest
         ▼
  the transcript (chips) + the evidence (what was read)

Four properties fall out of that shape, and each is a test:

The honest limitation, up front

The ACP wire this app speaks carries {type: "text"} and nothing else (api/adapters/acp/runtime.py:197 and :218), and none of the 27 tools reads a byte range from a binary file. So "attach an image to a vision model" cannot mean "send the pixels".

It means: the server describes the image and exposes its bytes to a tool, and the manifest says exactly what the model was given. On a model with no vision the image is still accepted — the chip says "not visible to this model" and the manifest tells the model to ask rather than guess — because a refusal would leave the user no way to hand over a screenshot at all.

Sending a real image content block is D7 option B — named, not done, and repeated in 11 so nobody discovers it later and calls it a bug.

What must be true when this is done

The short form; the long form is 03.

1. ⌘V with an image attaches it, and the chip exists before the upload starts.
2. Every refusal is one sentence naming the limit and the value.
3. An image on a model that cannot see is refused before the upload, naming the model.
4. Writing a blob into the workspace goes through the fence, with the same approval as Save.
5. The transcript reproduces on reload, from the event log, with the same chips.
6. The model receives a fenced description, never base64, and can page the rest through a tool.
7. The composer's resting height does not change by a pixel.
8. a11y 0, overflow 0, CLS ≤ baseline — the 007 bar, unchanged.

What this changes in code, at a glance

≈ 1,830 lines of implementation, ~124 unit tests, 10 e2e scenes. The estimate and its risk per phase are in 08 §effort.

Status of the documents