# Agent quickstart: author, validate, preview, share

**Install the workflow:** `npx skills add jaywolters/rodloom-skills --skill rodloom`. The [Rod Loom skill guide](install-skill.md) explains installation, MCP setup, and the HTTP fallback. Installing a skill does not automatically connect tools or enable vision.

**Hosted API origin:** `https://304heq9dze.execute-api.us-west-2.amazonaws.com`

The hosted Lambda API and local Python server support the endpoints below. These are not same-origin `rodloom.com/api/*` routes; publishing the static site alone does not enable a backend. For local use, run `python server.py` and use `http://localhost:8000` as the API origin. No authentication, persistence, browser, or third-party image services are required. Do not send sensitive data.

**For direct visual feedback to an image-capable agent:** connect the [Rod Loom MCP server](mcp.md) at `https://304heq9dze.execute-api.us-west-2.amazonaws.com/mcp` and call `preview_design` with `{ "design": <full design JSON> }`. It returns a native PNG image content block plus validation results. The client must pass image content to the model; otherwise, use the download-and-open workflow below and describe unseen designs as unpreviewed.

## 1. Choose actual catalog identities

Download `/assets/catalog.json` from the static site, or use the bundled file. For example, from this checkout:

```sh
node -e "const c=require('./assets/catalog.json'); console.log(c.items.filter(t=>t.brand==='ProWrap' && t.line==='ColorFast').slice(0,5))"
```

Copy `brand`, `sku`, `name`, `finish`, and, when supplied, `line` and `code` exactly. Add `catalog: true` and an illustrative `color: '#RRGGBB'`. Catalog swatches are photo references, not manufacturer RGB values. The API uses the bundled catalog offline; it does not fetch caller-provided URLs. Catalog stock flags are snapshots, not live inventory.

## 2. Build full design JSON

This is the **full import format**, not the compact share-link payload:

```json
{
  "version": 1,
  "name": "Yellowfin trim",
  "threadSize": "D",
  "coverage": 0.25,
  "diameter": 15,
  "blank": "#263a40",
  "texture": true,
  "bands": [{
    "name": "101 Yellowfin",
    "color": "#d8b43c",
    "finish": "regular",
    "brand": "ProWrap",
    "line": "ColorFast",
    "sku": "CFS-D-101",
    "code": "101",
    "catalog": true,
    "wrap": "solid",
    "turns": 40
  }]
}
```

For paired spirals use `wrap: 'spiral'`, `direction: 1` or `-1`, and a `secondary` thread object with the same thread fields (no turns). Both strands consume one coverage width per revolution: solid width = `turns × coverage`; paired spiral width = `turns × 2 × coverage`. `diameter` is blank diameter, in mm. Size A and D coverage starting estimates are 0.15 and 0.25 mm respectively.

Limits: 250,000 request bytes, 500 bands, 1–1,000 integer turns per band, 500 optional `quickColors`, 80-character names, coverage 0.05–1 mm, diameter 1–50 mm. Explicit version, size, texture, dimensions, blank, name and bands are required. See [schema](design.schema.json) and [paired example](example-design.json). Empty bands are allowed and show a bare blank.

## 3. Validate and inspect

From the checkout, using the bundled paired example (substitute your design file):

```sh
API_BASE=https://304heq9dze.execute-api.us-west-2.amazonaws.com
# For local use instead: API_BASE=http://localhost:8000
curl --fail-with-body "$API_BASE/api/validate" \
  -H 'Content-Type: application/json' \
  --data-binary @agents/example-design.json
curl --fail "$API_BASE/api/preview" \
  -H 'Content-Type: application/json' \
  --data-binary @agents/example-design.json -o preview.png
```

`POST /api/validate` returns JSON with `valid`, `catalogChecks`, `totalWidthMm`, `finishedRevolutions`, `estimatedThreadMeters`, per-SKU `threads`, and `warnings`. The paired example is 8 mm wide. Thread estimates use helical length at `π × (diameter + coverage)` circumference, with two strands for spirals. Setup turns, tag ends and waste are excluded. Size A products must be verified separately because catalog identities reference Size D.

`POST /api/preview` accepts the same JSON and runs the same checks before returning a **1200 × 720 PNG** (`Content-Type: image/png`). It includes the bottom rod face and full unrolled flat view at a shared proportional scale. Download and **inspect the actual image** before claiming a design looks good. No design is saved. Successful design responses have `Cache-Control: no-store`.

The dependency-free renderer uses the browser's physical width and spiral equations, but its finish shader and texture are illustrative, not pixel-identical to browser export. Fine turns are blended at subpixel widths; use browser zoom for detail. Colors are supplied estimates, not catalog color measurements. Previewing does not establish physical fit, guide-foot clearance, or real-world color accuracy.

Failures return JSON `{ "error": "..." }`: 400 malformed JSON/base64, 413 oversized body, 415 wrong content type, 422 invalid design or catalog mismatch, 405 wrong method, 500 processing failure. The renderer never fetches images or executes submitted code. Do not treat an error response as an image.

## 4. Generate a share link

```sh
node agents/create-link.cjs agents/example-design.json
```

Return the resulting URL as a clickable **Open in Rod Loom** link. It is self-contained, not a persistent short link, and must fit the 8,000-character limit. It loads a local draft; it does not save to the recipient's named library. For oversized links, provide the full JSON for **Design library → Import**. See [share links](share-links.md) for the compact codec and browser/Node examples.
