The Inspired handbook.

The Inspired Handbook

Reading the image, cutting the object out, shopping the cut.

Edition 1.0.0 · nine chapters · about 5,500 words · HTML and PDF.

The book about why the platform is built the way it is. The quickstart tells you which endpoint to call and the reference tells you what the fields mean. Neither tells you:

• why a read takes minutes and cannot be made to take seconds,
• why extraction is deliberately sequential when parallel would be four times faster,
• why your request is charged before any work happens,
• why a 404 refuses to say whether the read exists,
• or why the product is only allowed to say spotted and visually similar.

Each of those is a decision with a reason, and the reason is the difference between integrating against this platform and fighting it.

Chapters

1. What this actually does — the three moves, why the middle one exists, and the five things deliberately absent.
2. The pipeline — stage by stage, why the cut is sequential, how search overlaps it, and the two retailer gates.
3. Durability — one Workflow step per unit of paid work, the verdict that must not be retried, the picker that never blocks, and why an id is an idempotency key.
4. Focus domains — what a domain owns, why fashion is frozen by a test, what changed when the subject generalised and what was dropped rather than faked.
5. Keys and allowance — the key that exists in one email, charging in the WHERE clause, and what is refunded.
6. The two surfaces — HTTP and MCP over one code path, what MCP changes about results, and what the transport honestly does not implement.
7. Reading a result — the fields that carry meaning, what is missing and is meant to be, and which images expire.
8. Failure — every error with whether it was charged and whether to retry, and the three that get handled wrongly.
9. The honesty contract — the vocabulary, and why it is a technical constraint rather than a style guide.

Who it is for

Someone integrating Inspired who wants the reasoning, a developer inheriting that integration, or anyone building a similar pipeline who would rather read about these decisions than rediscover them.

Editions

Both editions are generated from the same nine chapter files, so they cannot drift apart:

• HTML — one self-contained page, dark-on-light, readable on a phone, with a contents list. No scripts, no fonts, no requests.
• PDF — the same text, paginated, for reading away from a browser.

Limits

It documents the platform deployed at inspired.jetskibay.com in September 2026, and says where behaviour might change. It contains no verbatim prompt text — the article Ask for the shirt, get the vest, published beside it, covers the prompt design. It is a handbook, not a tutorial: it assumes you can already make an HTTP request and would rather know why than be shown how.

I've attached The Inspired Handbook. I'm the second developer on an integration
someone else built and left, and I need to review it before we put it in front
of customers.

Use the handbook as the source of truth for intended behaviour, and tell me
where our code disagrees with it:

1. Read chapters 2 and 3, then look at how we call Inspired. If we are treating
   a read as a request rather than as a durable job — a long HTTP call, a
   timeout, a retry that starts a new read — say so, and quote the part of
   chapter 3 that explains why the request id is the idempotency key.
2. Read chapter 5 and audit our retry logic against it. I specifically want to
   know: do we retry on quota_exhausted, do we start a second read when a start
   call times out, and do we treat an empty items array as a failure worth
   retrying? Chapter 8's table says which of those cost us a request.
3. Read chapter 7's "Progress, while it runs" and tell me what our loading state
   does. If it is a spinner, tell me exactly what data is already in the poll
   response that we are ignoring.
4. Read chapter 9, then grep every user-facing string in the repository and flag
   each one that claims more than the pipeline can support. Use its two tables
   as the rule — I expect "match" and "found" to be all over our code.

Two constraints. Do not propose adding a verification or scoring step to justify
stronger copy; chapter 9 is explicit that the pipeline does not do that, and
building it is a separate decision, not a review finding. And do not propose
switching to POST /api/v1/inspire to simplify anything — chapter 6 says what
that route is for.

Finish with a prioritised list: which of these will cost us money, which will
cost us credibility, and which are merely untidy.