# Create Rod Loom designs with an AI agent

Rod Loom is a free fishing rod thread design tool at https://rodloom.com/. Generate a design for solid bands and paired spiral fades without calling a service. Prefer returning a clickable URL that opens the design directly: see https://rodloom.com/agents/share-links.md. This guide describes the full version 1 JSON format used for file import and as input to the reference link encoder.

## Resources

- Discovery: https://rodloom.com/llms.txt
- Schema: https://rodloom.com/agents/design.schema.json
- Working example: https://rodloom.com/agents/example-design.json
- Catalog: https://rodloom.com/assets/catalog.json
- Designer and import UI: https://rodloom.com/

## Workflow

1. Ask for color preferences, Size A or D, approximate wrap length, blank diameter, and whether the builder wants solid bands, paired fades, or symmetry. If unknown, explicitly label any assumptions; a 15 mm blank and 0.25 mm/turn Size D coverage are planning defaults, not measured values.
2. Fetch the catalog and choose actual entries by brand, line, name, and SKU. The `items` array contains Size D references. Copy `name`, `brand`, `finish`, `sku`, and preferably `line`, `code`, and `source` from each selected entry. Add `catalog: true` and an approximate six-digit hex `color`.
3. Build `bands` in left-to-right wrapping order. Solid bands use one thread; spiral bands use an outgoing thread at the band level and an incoming thread under `secondary`. Use integer `turns` and explicit `wrap` values.
4. Check the schema and the dimensions below. Use the share-link reference encoder to turn the full design into a validated URL. Return a clickable **Open your design in Rod Loom** link, or navigate there with browser tools when asked. Do not encode full import JSON directly into the URL; the compact link format is different.
5. If the design exceeds link limits, return a UTF-8 JSON attachment at or below 250,000 bytes (or a JSON code block to save as a `.json` file). Tell the user: open https://rodloom.com/, expand **Design library**, choose **Import**, and select the JSON file. Import can prompt about unsaved changes; do not discard the user's work without consent. Inspect the rod and flat previews, then use **Recipe** for printing or **Save as PDF**. Use **Export** to back up the editable JSON and **Export image** for PNG.

The Python backend supports `POST /api/validate` and `POST /api/preview` for full design JSON; see the [agent quickstart](quickstart.md). Use the local server or the hosted API origin listed in the quickstart, not `rodloom.com/api/*`: static-only hosting does not enable a backend. There is no hosted generation, upload, or cloud-save endpoint, and neither validation nor rendering persists a design. No account, API key, or personal data is needed to produce a design file.

## Top-level fields

| Field | Type and constraint | Meaning |
| --- | --- | --- |
| `version` | integer `1` | Include for generated files; the importer normalizes to version 1. |
| `name` | string, maximum 80 characters | Human-readable design name. |
| `threadSize` | `A` or `D` | Include explicitly; legacy files without it default to D. |
| `coverage` | number, 0.05–1 inclusive | Millimeters covered by one turn of one thread. Defaults are 0.15 for A and 0.25 for D; measure a test wrap for accuracy. |
| `diameter` | number, 1–50 inclusive | Rod blank diameter in millimeters. |
| `blank` | `#RRGGBB` string | Preview blank color. |
| `texture` | boolean | Whether to display individual thread turns. |
| `bands` | array of bands | Wrapping order; empty is allowed for a blank design. |
| `quickColors` | optional array, maximum 500 threads | Collected palette; not required to render bands. |

The published schema is a recommended authoring contract, not an exact description of all legacy values accepted by the importer. It requires explicit version, size, and boolean texture for predictable generated files. Import does not fetch or verify SKU membership, so agents must verify identities against the catalog themselves.

## Thread and band fields

Each thread requires:

- `name`: string, at most 80 characters; copy the catalog name.
- `color`: six-digit hex color, for example `#d8b43c`.
- `finish`: `regular`, `metallic`, or `neon`; copy the catalog finish.
- `brand`: `Fuji` or `ProWrap`.
- `sku`: nonempty string; use the real catalog SKU.
- `catalog`: literal `true`.

Optional thread metadata: `line`, `code`, and `source`. For portability, keep SKU, line, and code to at most 160 characters (quick palette constraints). Catalog items do not contain canonical RGB values. Resolve their `image` paths relative to https://rodloom.com/ to inspect swatches, or supply a clearly disclosed visual approximation. Do not invent manufacturer color specifications. Stock flags and product metadata are bundled snapshots, not live availability guarantees.

Every band also needs `turns`, an integer from 1 to 1000. A solid band has `wrap: "solid"` (legacy solid bands may omit `wrap`). A spiral band has `wrap: "spiral"`, a complete incoming thread in `secondary`, and `direction: 1` or `-1` for opposite spiral orientations. The band's main thread is outgoing. A typical transition is solid A, spiral A→B, solid B.

Optional band grouping: `group` is a nonempty string up to 80 characters; adjacent bands with the same identifier form a group. `groupName` is a string up to 80 characters. These are editor organization features, not extra thread turns.

## Width and thread estimates

For coverage `c` in mm/turn and `n` turns:

- Solid width: `n * c` mm.
- Paired spiral width: `n * 2 * c` mm (two strands side by side).
- Total width: sum of band widths.
- Approximate thread length per band, in meters: `n * s * hypot(PI * (diameter + c), c * s) / 1000`, where `s` is 1 for solid or 2 for spiral. This is the combined length of both strands for a spiral.

For example, 12 solid turns, 4 paired spiral turns, and 12 solid turns at 0.25 mm/turn occupy `(12 + 2*4 + 12) * 0.25 = 8 mm`. Spiral counts are finished paired revolutions, not individual strand counts. Round desired widths to whole turns and report the resulting dimensions rather than promising an exact arbitrary length.

Allow extra thread for setup, tie-offs, tag ends, and waste; these are excluded from the estimate. Changing Size A/D preserves turn counts, not physical widths. Catalog photos and product links are Size D references even when a design uses Size A; verify corresponding Size A products separately.

## Boundaries and honest output

- This format supports solid bands and paired fades, not decorative diamond/cross-wrap simulations or taper-compensated layout spacing.
- Colors, metallic effects, and neon effects are illustrative. Recommend physical samples before buying or wrapping.
- PNG exports and printed recipes are not calibrated life-size templates. Actual-size screen viewing needs user calibration.
- Designs live in browser storage, not in a shared cloud account. Clearing site data removes saves; recommend JSON backups.
- Describe a generated design as unpreviewed unless you actually inspected its browser preview or endpoint-generated PNG. Passing a schema does not prove the pattern looks good or will wrap exactly as estimated.

## Example

Download https://rodloom.com/agents/example-design.json. It uses two real ProWrap ColorFast entries, 12 solid turns of Yellowfin, 4 paired turns transitioning to Banana Split, and 12 solid turns of Banana Split. The supplied hex colors are illustrative approximations, not sampled or manufacturer-certified values. Its planned width is 8 mm at the included Size D coverage.
