# Contents, and how to read it

Nine chapters, about an hour end to end. It is short enough to read straight
through, and the chapters are ordered so that each one uses the previous one's
conclusion.

## Read in order, if you are starting

**1. What this actually does** and **2. The pipeline** together explain the one
fact everything else follows from: a photograph of an outfit is one image
containing six products, so the cut has to happen per object before anything can
be searched. That requirement produces the sequential extraction, the
multi-minute read, and the whole durable architecture.

**3. Durability** is the chapter to read before you design a client. It explains
why the read is a job rather than a request, and therefore why your client is
allowed to be almost nothing.

## Read on demand

- **4. Focus domains** — before your first non-fashion read.
- **5. Keys and allowance** — before you write a retry policy. Especially the
  charged-at-the-start section.
- **6. The two surfaces** — when choosing between HTTP and MCP, or when you want
  to know what the MCP transport does not implement.
- **7. Reading a result** — while writing the code that consumes it.
- **8. Failure** — when something breaks. It is a table first, prose second.
- **9. The honesty contract** — before you write any user-facing copy.

## The four sections worth reading even if you skip the rest

1. **Chapter 2, "The cut, and why it is sequential."** The reason the API is
   slow, in one page. If you were planning to ask for a faster mode, this is the
   answer.
2. **Chapter 5, "Charged at the start."** Includes the actual SQL. It explains
   why ten concurrent calls cannot share one remaining request, and why an empty
   result still costs you.
3. **Chapter 7, "Progress, while it runs."** How to make a three-minute read
   feel like progress rather than a hang. The data is already in the response;
   this is the cheapest quality win available.
4. **Chapter 9, all of it.** Two pages on the words your product may use, and
   why the constraint is architectural rather than editorial.

## Relationship to the other publications

- The **visual search guide** is the practical companion: what to do, in order,
  with a shipping checklist. This handbook is the reasoning behind it.
- The **article** *Ask for the shirt, get the vest* goes deep on one chapter's
  worth of material — the extraction prompt — and is the only place the prompt
  clauses are quoted.
- The **focus-domain dataset** is chapter 4 as machine-readable data.
- The **CLI** and the **agent skill** are the two working clients.

## Conventions

A fenced block is either a request, a response or a diagram, never pseudocode
pretending to be either. Where a behaviour is a deployment detail that could
reasonably change, the text says so instead of presenting it as a guarantee.
Field names are written exactly as the API spells them.