# Product spec — from the jeweler (Sharif Jewelers, Jun 2026 iMessage thread)

The customer for this system is a working jeweler. His actual workflow, in his
words and examples:

## The core flow: reference + modification

> "Today I got someone who asked me to make this ring but instead of emerald
> center stone they want elongated cushion."

Customers arrive with a REFERENCE (TikTok/Instagram video, photo, another
ring) plus a MODIFICATION (different center cut, metal, carat, band style).
The agent's job: turn that into a spec (`prompts/design.md`), build via
`ringcli`, and show a render the jeweler can send back to the customer.

This maps 1:1 onto the existing harness: the eval already judges builds
against reference photos, and the spec's `cut`/`carat`/`metal`/`archetype`
fields are exactly the modification axes customers use.

## Output target: 3D print for lost-wax casting

- Rings are resin-printed then cast; prints need SUPPORT STEMS / a SPRUE
  (his example: CAD with green stems under the shank and head).
- **Beta scope (his call): skip supports.** "If it makes it easier as a beta
  we can do without at first — see the quality of CAD renders and then get
  more detailed after."
- **Done (ringcli v2):** every build emits a single fused watertight metal
  body as `<name>-cast.stl` — walls/prongs/beads at casting floors (1.0 /
  0.8–0.6 / 0.5 mm), stones seated in cut pockets, azure-drilled pavé —
  gated by `ringcli/validate.py` (one valid solid, mass sanity, stones held).
- **Done (ringcli/supports.py):** every build also emits `<name>-print.stl` —
  the cast body with a main sprue under the shank plus two angled feeder
  stems (the green stems from his reference screenshots). Renders show them
  in green on a high-contrast CAD palette. Full casting-tree layout and
  shrinkage compensation (1–3%) stay the caster's job.

## Production pipeline (commercial: real ring, real diamond)

`"production": true` + `stone_mm` (cert dims) switches the build from
eval-styled to commercially settable geometry:

- exact stone dims — no photogenic scaling; ruled-loft gems (exact girdle)
- straight over-length prong blanks (setter cuts the bearing and bends);
  bezel gets an absolute burnish lip + clearance
- seats cut by true 3D offset at 0.08 mm bearing clearance; hard-fail if any
  seat cut is incomplete; gates check gap window, ring ID ±0.05 mm, and
  per-alloy mass sanity
- deliverables per job: print STL (optionally pre-scaled for shrinkage,
  factor in the filename), seat-fit coupon STL (cheap resin test with the
  real stone before casting), work-order HTML (dims, alloy weights,
  print/cast/setting instructions, QC checklist)
- `ringcli calibrate` emits sized test bands to dial in the shop's
  print+cast shrink factor once

v2 roadmap: calibrated-melee halo/pavé fits, V-prongs for sharp corners,
multi-ring casting trees.

## Product flow (Telegram → studio → print)

Target deployment: Claude Code runs on a server; a Telegram bot forwards each
message as one design request. The agent builds the concept and replies with a
link to **`/viewer/design.html?name=<design>`** — the customer studio page:

1. spin the 3D model, see the renders
2. leave notes ("thinner band", "rose gold") → `/api/comment` → the agent
   picks them up, rebuilds, same link updates
3. **Approve** → `/api/produce` runs the production build server-side
   (exact seat, settable prongs, work order, coupon, print STL)
4. **Email me the files** → `/api/email` sends the work order + STLs via
   AgentMail (set `AGENTMAIL_API_KEY` + `AGENTMAIL_INBOX` in `.env`)

Access control: the bot only serves chat ids in TELEGRAM_ALLOWED_CHATS
(.env, comma-separated; unknown senders get a polite denial that includes
their chat id so the owner can allowlist them). Studio links carry a
per-design HMAC token minted under STUDIO_SECRET (auto-generated into .env
on first server boot); the token unlocks that design's data and files only,
via query param or cookie. Internal pages (review/eval) use the admin token
printed at server start. No secret set = open local dev mode.

## Beta deliverable bar

Quality CAD renders of the modified design, fast iteration on feedback
("I'll make something that does this and we can iterate"). The review UI +
comment loop is the iteration surface.