# Pibot for AI agents

Pibot turns a plain-language idea into a working machine: real parts with in-stock links, a 3D physics simulation, a fit check (volts, amps, logic levels, connectors, screws, millimetres), one checkout for every shop, and software that installs on the person's own Raspberry Pi. It also sells ready-made robots to program. This page tells an agent (Claude, ChatGPT, a coding agent or a browser agent) how to help a person through it.

Pibot does not run your reasoning: you do, on the person's own AI plan or compute. Pibot gives you the tools.

## Rules

1. **Never order or pay without the person's explicit yes.** Show the full list (items, shop, quantity, price, shipping, fee, total) and wait for a clear yes before `create_order`, and again before any payment.
2. **Payments go through the person's Swiss Vault account** (swissvault.app), within the limits they set there. Never ask for card numbers, seed phrases or private keys.
3. **Only link products that are in stock.** Use the `check_stock` tool or `GET /api/buy?part=<id>`.
4. **Keep data on the device.** Skills run on the Pi; don't send camera images or audio to the cloud.
5. **Approve money explicitly.** A machine can propose a payment; a person approves it. Never approve on the person's behalf.
6. **Pibot can't do something?** Say so, and send it to `POST /api/suggestions` `{ "title", "detail" }` (or the `suggest_feature` tool).

## Three ways to connect

- **MCP connector** (best): `https://pibot-14g.pages.dev/api/mcp` (streamable HTTP). Claude: Settings → Connectors → Add custom connector. Claude Code: `claude mcp add --transport http pibot https://pibot-14g.pages.dev/api/mcp`. Tools: `list_templates`, `list_robots`, `search_parts`, `part_details`, `check_stock`, `complete_and_check`, `studio_link`, `checkout_link`, `create_order`, `order_status`, `suggest_feature`. Order tools need the person's owner key as `Authorization: Bearer <key>` (they find it on the Connect AI page).
- **Browser agent** (Claude in Chrome and others): open the site and work in it. Every page has `window.pibot`: `pibot.studio(description)`, `pibot.parts(query)`, `pibot.addToCart(id, qty, offer)`, `pibot.cart()`, `pibot.checkout()`, `pibot.fitCheck([[id, n], …])`. Robot Studio also exposes `pibotSim` and the Part Lab `pibotLab`.
- **HTTP API**: the endpoints below.

## Flow

1. **Ask** what the machine should do, where (city, indoor/outdoor), size and budget.
2. **Ready-made or from scratch?** If a ready-made robot fits (`list_robots`, `/robots.html`), suggest it: buy it built, then program it. Otherwise design one.
3. **Pick the mechanism**: `GET /api/products/tasks` lists jobs; `GET /api/products/tasks/<task>?region=<shenzhen|hongkong|uk|eu|us|other>` ranks every way to do it.
4. **Show and simulate it**: `https://pibot-14g.pages.dev/robot.html?q=<description>` (or `?kit=<id>`). It builds the assembly from real parts, wires it, adds everything needed to work (SD card, supplies, cables, connectors) and runs physics. Each part opens in the Part Lab (pick the exact product, anatomy, physics, connectors, pin-by-pin wiring).
5. **Fit check**: `complete_and_check` with `[[partId, count], …]`. Fix every `fail` before ordering; explain each `warn`.
6. **Order (with the person's yes)**: `checkout_link` gives a prefilled cart for them to review, or `create_order` with `{ items: [{ part, qty, offer? }], contact: { name, email, phone }, ship: { line1, line2, city, postcode, region, country }, accept: true, swissvault: true }` after they confirmed the items, address and the ordering terms (`/terms.html#ordering`).
   - The order desk adds each shop's shipping (status `awaiting_payment`). `order_status` then returns `payment` with a ready Swiss Vault AgentBank call: `POST /v1/payments` `{ to, amount, memo, idempotencyKey }` on the person's Swiss Vault (local, `http://127.0.0.1:4280` by default).
   - After paying, send the transaction hash: `POST /api/checkout/<id>/paid` `{ "tx": "0x…" }` (owner key). Pibot checks the USDC transfer on-chain.
   - Pibot buys each item from its shop and posts tracking per shop on the order.
7. **Deploy**: on the Pi (also the Pi inside a ready-made robot)
   `curl -fsSL https://pibot-14g.pages.dev/agent/install.sh | PIBOT_ORIGIN=https://pibot-14g.pages.dev bash`
   and enter the code it shows at `https://pibot-14g.pages.dev/devices.html`. Without a Pi, run the agent with `--simulate`.
8. **Install skills and apps** (owner key as bearer): `PUT /api/devices/<id>/skills/<skill>` `{ params }`, `POST /api/devices/<id>/apps/<app>` `{ action: "install" }`, `POST /api/devices/<id>/chat` `{ text }`.

## Catalogues

- Skills: `GET /api/skills` · Apps: `GET /api/apps` · Components with live stock: `GET /api/products/components`
- Parts, templates and ready-made robots: `/assets/parts.js` (`PARTS`, `KITS`), `/assets/robots.js`
- Engineering data per part (ratings, connectors): `/assets/partdata.js`