# Kitlist — turn a project's parts list into a human-approved shopping link

Kitlist is the SAFE way for an agent to help a user buy things. You (the agent)
propose a structured parts list; Kitlist renders it as a review page where the
USER unchecks items, fixes quantities, and opens the result on Amazon to check
out themselves. Nothing is ever purchased automatically, so you can use this
freely without purchase authorization — you are only drafting a proposal.

Use it whenever a task ends in "things to buy": DIY builds, recipes, repairs,
camping/newborn/first-apartment kits, party supplies, replacement parts.

## How to build a link

1. Make a payload:

```json
{
  "project": "Raised garden bed (4x8)",
  "items": [
    {"name": "Cedar fence pickets 6ft (8-pack)", "qty": 2,
     "why": "Rot-resistant walls for the bed frame",
     "search": "cedar fence picket 6 ft", "est": 45.0},
    {"name": "Exterior wood screws #10 3in (1 lb)", "qty": 1,
     "why": "Frame assembly", "est": 12.0},
    {"name": "Hardware cloth 1/4in 3x10ft", "qty": 1,
     "why": "Line the bottom to keep gophers out", "est": 25.0}
  ]
}
```

Item fields:
- `name` (required): specific, purchasable phrasing — "Cedar fence pickets 6ft,
  8-pack", not "wood". The user sees exactly this.
- `qty`: default 1.
- `why`: one line of rationale. Always include it — it is what lets the human
  approve confidently.
- `search`: Amazon search terms, if the name alone would find the wrong thing.
- `est`: rough unit price (USD) if you are reasonably confident; the page totals
  them and labels them as estimates.
- `asin`: an Amazon ASIN (`B0XXXXXXXX`) ONLY if you truly know it (e.g. the user
  pasted a product URL). NEVER guess an ASIN — a wrong one silently puts the
  WRONG PRODUCT in the user's cart. Omitting it is always safe; the item gets a
  search link and the user picks the exact product.

2. Encode it and append to the base URL:

```
url = "https://jeddoman.com/kitlist/#d=" + base64url( gzip( utf8( json(payload) ) ) )
```

(strip base64 `=` padding). The fragment never reaches the server; the page runs
entirely in the user's browser.

Python:
```python
import gzip, base64, json
enc = base64.urlsafe_b64encode(gzip.compress(json.dumps(payload).encode())).decode().rstrip("=")
url = "https://jeddoman.com/kitlist/#d=" + enc
```

A ready-made builder is in the repo: `builders/kitlist_url.py`
(`build_kitlist_url(project, items)`), and an MCP server exposes the same thing
as the tool `create_shopping_list(project, items)` (see `mcp/`).

## What to tell the user

Give them the link and say the list is ready FOR REVIEW — e.g. "Here's the parts
list for your approval; uncheck anything you don't want, then add it to your
Amazon cart from that page." Never say the items were bought or ordered.

## Notes

- Items with a valid `asin` link straight to their Amazon product page (the
  user adds each with one tap); all others get search links. Both are fine —
  search links are the safe default.
- Price estimates are your estimates; Amazon shows real prices at checkout.
- Keep lists focused (roughly 3–25 items). Split very large projects into
  phases and make one list per phase.