# Mollie's Stitch Studio

Mollie's Stitch Studio is a working proof of the safest architecture for sending custom embroidery designs to a Brother SE700 without leaving a Mac running.

For a copy-paste brief to give Mollie's local coding agent, see [MOLLIE_AGENT_HANDOFF.md](MOLLIE_AGENT_HANDOFF.md).

The VPS stores validated designs. A native iPhone app downloads an approved PES file, finds the SE700 on the same Wi-Fi network, and performs the local transfer only after Mollie confirms it.

## What works now

- Deterministic embroidery designs assembled from typed geometry.
- Real PES compilation with `pyembroidery`.
- PES decode and validation for hoop bounds, stitch length, stitch count, and upload size.
- Technical SVG stitch previews generated from the decoded PES.
- An authenticated VPS queue at `https://stitch.204.168.230.132.sslip.io`.
- A native SwiftUI iPhone companion with Keychain pairing.
- Same-Wi-Fi SE700 discovery, exact model verification, and certificate pinning.
- ChatGPT can request a phone-side transfer without receiving LAN access or machine-write capability.
- Explicit approval before upload and delivery verification afterward.
- Exact Brother `pedxml` multipart upload behavior based on the open-source protocol notes credited in `THIRD_PARTY_NOTICES.md`.

The backend and iPhone app are built and tested. No file has been uploaded to the physical machine yet. That remains an intentional, separately confirmed action.

## Architecture

```text
ChatGPT design conversation
          |
          v
typed design recipe -> PES compiler -> decode and validate -> VPS queue
                                                            |
                                                            v
                                                  native iPhone app
                                                            |
                                                   same home Wi-Fi
                                                            |
                                                            v
                                                      Brother SE700
```

The VPS cannot directly reach a machine inside the home network. The iPhone is the secure local relay because it can access both HTTPS on the internet and the SE700 on the local Wi-Fi. ChatGPT can stage a transfer request in the VPS queue, but only the foreground iPhone app can discover the machine and perform the upload after Mollie confirms it.

PES is a compiled binary machine format containing ordered stitch, jump, trim, color-change, and end commands. SVG is used only as an editable or reviewable intermediate. An ordinary image is not automatically a safe embroidery design.

## Reliability by design source

| Input | Expected automation reliability | Notes |
|---|---:|---|
| Parametric text, borders, icons, and geometry | 90 to 95 percent | Best first release because stitch rules are explicit. |
| Clean vector artwork with limited colors | 75 to 90 percent | Needs path cleanup and stitch presets. |
| Constrained AI line art | 65 to 85 percent | Needs vectorization, simplification, and validation. |
| Photos, gradients, and painterly imagery | 30 to 50 percent | Needs real digitizing judgment and is not an automatic one-click conversion. |

These ranges estimate stitch quality without manual editing. PES validity and LAN transfer can be deterministic, but fabric, stabilizer, needle, thread, tension, and hooping still affect the physical result. Every new design class should receive a sample stitch-out.

## Run the backend locally

```bash
uv sync --python 3.12
export STITCH_STUDIO_PAIRING_TOKEN="replace-with-a-long-random-token"
export STITCH_STUDIO_PUBLIC_BASE_URL="http://127.0.0.1:8900"
export STITCH_STUDIO_DATA_DIRECTORY="$(pwd)/work/jobs"
uv run stitch-studio-api
```

Run the checks:

```bash
uv run ruff check .
uv run pytest -q
uv run stitch-studio generated
uv run stitch-machine-status 192.168.1.112
```

The status command is read-only. Do not run a physical upload as an unattended test.

## Run the iPhone app

The Xcode project is generated from `ios/project.yml` with XcodeGen.

```bash
cd ios
xcodegen generate
open MolliesStitchStudio.xcodeproj
```

To install on a real iPhone, select an Apple development team in Xcode under Signing & Capabilities, connect the phone, and run the app. This Mac currently has no valid Apple code-signing identity, so the source builds in Simulator but cannot yet be installed on a physical phone or sent through TestFlight.

Pairing requires the public server URL and the private token stored in the VPS environment. The token is saved in the iPhone Keychain and is not included in this repository.

## ChatGPT integration status

The OAuth-protected ChatGPT connector is live at:

```text
https://stitch.204.168.230.132.sslip.io/mcp
```

It implements Streamable HTTP MCP, dynamic client registration, OAuth authorization code with S256 PKCE, scoped access tokens, rotating refresh tokens, protected-resource discovery, and a private consent page.

To connect Mollie's account:

1. Sign in to Mollie's ChatGPT account.
2. Enable Developer mode in ChatGPT settings.
3. Choose Tools, Add, then MCP Server.
4. Enter the `/mcp` address above.
5. Enter the private connection password on the Stitch Studio consent page.
6. Start a new conversation and select Mollie's Stitch Studio from Tools.

The connection password is not stored in source or this README. On Jake's Mac it is stored in Keychain under `Mollies Stitch Studio ChatGPT`.

The MCP tools can describe the SE700 limits, list queued designs, compile a constrained one-color radial flower with 3 to 12 petals, and request a phone-side transfer. Each tool-created PES is decoded and validated before it appears in the iPhone queue.

When Mollie asks ChatGPT to send a design, the agent should call `request_machine_transfer` with the queued job ID. The response changes the job to `send_requested`; the iPhone queue refreshes while the app is open and labels the request. Mollie still opens the design, reviews the decoded preview, confirms the transfer, and starts sewing at the machine. ChatGPT never scans the home LAN and never claims a physical transfer until the phone reports delivery.

This separation prevents a chat session or remote VPS process from silently writing to the embroidery machine.

## Transfer safety

- The app verifies the PES signature and SHA-256 checksum before discovery.
- Discovery verifies Brother model `60`, type `3`, and `pedxml` version `1`.
- The known SE700 certificate fingerprint is pinned in the native client.
- The upload is never automatically retried after an uncertain write.
- The app compares the machine file list before and after upload.
- The VPS marks a job delivered only after a new machine file is observed.
- The operator still selects the design and starts embroidery at the machine.