stitch-kit 1.5.0

package/skills/stitch-mcp-list-screens/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: stitch-mcp-list-screens
+description: Lists all screens in a Stitch project. Use this after generate_screen_from_text to find the screenId of the newly generated screen, then call stitch-mcp-get-screen to retrieve it.
+allowed-tools:
+  - "stitch*:*"
+---
+
+# Stitch MCP — List Screens
+
+Lists all screens contained within a specific Stitch project. You typically call this right after `generate_screen_from_text` to find the `screenId` of the screen that was just created.
+
+## Critical prerequisite
+
+**Only use this skill when the user explicitly mentions "Stitch".**
+
+## When to use
+
+- Immediately after `generate_screen_from_text` — to find the new screen's ID
+- User wants to browse all screens in a project
+- You need a `screenId` to call `get_screen`
+- Checking what screens already exist before generating a new one
+
+## Call the MCP tool
+
+**Important: Use the `projects/ID` format — not the numeric ID alone.**
+
+```json
+{
+  "name": "list_screens",
+  "arguments": {
+    "projectId": "projects/3780309359108792857"
+  }
+}
+```
+
+```
+✅ "projects/3780309359108792857"
+❌ "3780309359108792857"
+```
+
+## Output schema
+
+```json
+{
+  "screens": [
+    {
+      "name": "projects/3780309359108792857/screens/88805abc123def456",
+      "title": "Login Screen",
+      "screenshot": {
+        "downloadUrl": "https://storage.googleapis.com/..."
+      },
+      "deviceType": "MOBILE"
+    }
+  ]
+}
+```
+
+## After listing
+
+1. Identify the target screen (usually the most recently generated — last in the list)
+2. Extract the numeric `screenId` from the `name` field:
+   - `"projects/3780309359108792857/screens/88805abc123def456"` → screenId = `"88805abc123def456"`
+3. Call `stitch-mcp-get-screen` with the numeric `projectId` and `screenId`
+
+## ID format reminder
+
+For the next call (`get_screen`), you need the **numeric IDs** for both project and screen:
+- `projectId` → `3780309359108792857` (strip `projects/` prefix)
+- `screenId` → `88805abc123def456` (strip `projects/.../screens/` prefix)

package/skills/stitch-mcp-update-design-system/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: stitch-mcp-update-design-system
+description: Updates an existing Stitch Design System's theme, tokens, or guidelines. Requires the asset name from create or list operations.
+allowed-tools:
+  - "stitch*:*"
+---
+
+# Stitch MCP — Update Design System
+
+Updates an existing Stitch Design System. Use this to modify theme properties, design tokens, or style guidelines without creating a new design system.
+
+## Critical prerequisite
+
+**Only use this skill when the user explicitly mentions "Stitch".**
+
+You must have the design system's asset `name` before calling this. If you don't have one:
+- List existing design systems via `stitch-mcp-list-design-systems`
+- Or use the `name` returned from `stitch-mcp-create-design-system`
+
+## When to use
+
+- User wants to modify colors, fonts, or roundness of an existing design system
+- After reviewing a design system and wanting to adjust specific properties
+- Updating design tokens after a brand refresh
+
+## Call the MCP tool
+
+```json
+{
+  "name": "update_design_system",
+  "arguments": {
+    "designSystem": {
+      "name": "assets/ds_abc123",
+      "displayName": "SaaS Dashboard Theme v2",
+      "theme": {
+        "colorMode": "DARK",
+        "font": "GEIST",
+        "roundness": "ROUND_TWELVE",
+        "saturation": 2,
+        "customColor": "#818CF8",
+        "backgroundLight": "#F9FAFB",
+        "backgroundDark": "#09090B"
+      },
+      "designTokens": "--color-primary: #818CF8;\n--color-bg: #09090B;",
+      "styleGuidelines": "Dark mode first. Geist font. Subtle indigo accent."
+    }
+  }
+}
+```
+
+## Parameter reference
+
+### `designSystem` — required, Asset wrapper
+
+The object must include the `name` field (asset identifier) plus any fields you want to update:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Asset name from create or list (e.g., `assets/ds_abc123`) |
+| `displayName` | string | No | Updated human-readable name |
+| `theme` | DesignTheme | No | Updated visual configuration (see `stitch-mcp-create-design-system` for full reference) |
+| `designTokens` | string | No | Updated CSS custom properties |
+| `styleGuidelines` | string | No | Updated design rules |
+
+**Note:** This is a full replacement, not a merge. Include all theme fields you want to keep, not just the ones you're changing.
+
+## Output
+
+Returns the updated Asset object:
+
+```json
+{
+  "name": "assets/ds_abc123",
+  "displayName": "SaaS Dashboard Theme v2",
+  "designSystem": { ... }
+}
+```
+
+## After updating
+
+- Offer: "Re-apply this updated design system to existing screens?" → `stitch-mcp-apply-design-system`
+- Screens generated before the update won't automatically reflect changes — they need to be re-applied

package/skills/stitch-mcp-upload-screens-from-images/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: stitch-mcp-upload-screens-from-images
+description: Uploads screenshots or mockup images into a Stitch project as new screens. Enables the "redesign from screenshot" workflow — import existing UI and then edit or convert.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+---
+
+# Stitch MCP — Upload Screens from Images
+
+Uploads one or more images (screenshots, mockups, wireframes) into a Stitch project as new screens. This is the entry point for the "redesign existing UI" workflow — import what you have, then use `edit_screens` to iterate or convert directly to code.
+
+## Critical prerequisite
+
+**Only use this skill when the user explicitly mentions "Stitch".**
+
+You must have a `projectId` before calling this. If you don't have one:
+- Create a new project via `stitch-mcp-create-project`
+- Or find an existing project via `stitch-mcp-list-projects`
+
+## When to use
+
+- User provides a screenshot and wants to redesign it in Stitch
+- User wants to import existing mockups into Stitch for editing
+- The orchestrator classifies intent as "Upload screenshot"
+- User says "import this design", "upload this image", or "redesign this screen"
+
+## Step 1: Encode the image to base64
+
+Use the helper script to convert a local image file to base64:
+
+```bash
+bash scripts/encode-image.sh "path/to/screenshot.png"
+```
+
+The script outputs raw base64 to stdout. Capture it for the API call.
+
+Supported formats and their MIME types:
+| Extension | MIME type |
+|-----------|----------|
+| `.png` | `image/png` |
+| `.jpg`, `.jpeg` | `image/jpeg` |
+| `.webp` | `image/webp` |
+| `.gif` | `image/gif` |
+
+## Step 2: Call the MCP tool
+
+```json
+{
+  "name": "upload_screens_from_images",
+  "arguments": {
+    "projectId": "3780309359108792857",
+    "images": [
+      {
+        "fileContentBase64": "[base64-encoded-image-data]",
+        "mimeType": "image/png"
+      }
+    ]
+  }
+}
+```
+
+### `projectId` — numeric ID only, no prefix
+
+```
+✅ "3780309359108792857"
+❌ "projects/3780309359108792857"
+```
+
+### `images` — array of image objects
+
+Each image needs:
+| Field | Type | Description |
+|-------|------|-------------|
+| `fileContentBase64` | string | Base64-encoded image data (no `data:` prefix) |
+| `mimeType` | string | MIME type matching the image format |
+
+You can upload multiple images in a single call — each becomes a separate screen.
+
+## Output
+
+Returns session info similar to `generate_screen_from_text`. The uploaded images appear as new screens in the project.
+
+## After uploading
+
+1. Call `stitch-mcp-list-screens` to find the new screen IDs
+2. Offer the user:
+   - "Edit this screen (change colors, layout, content)?" → `stitch-mcp-edit-screens`
+   - "Convert directly to code?" → `stitch-mcp-get-screen` → framework conversion
+   - "Generate variants based on this design?" → `stitch-mcp-generate-variants`
+
+## References
+
+- `scripts/encode-image.sh` — Base64 encoding helper

package/skills/stitch-mcp-upload-screens-from-images/scripts/encode-image.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# encode-image.sh — Encodes an image file to base64 for the Stitch upload API.
+#
+# Usage: bash encode-image.sh "path/to/image.png"
+# Output: Raw base64 string to stdout (no wrapping, no data: prefix)
+#
+# Supports: PNG, JPG, JPEG, WebP, GIF
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: bash encode-image.sh <image-path>" >&2
+  exit 1
+fi
+
+IMAGE_PATH="$1"
+
+# Validate the file exists
+if [[ ! -f "$IMAGE_PATH" ]]; then
+  echo "Error: File not found: $IMAGE_PATH" >&2
+  exit 1
+fi
+
+# Validate the file is an image by extension
+EXT="${IMAGE_PATH##*.}"
+EXT_LOWER=$(echo "$EXT" | tr '[:upper:]' '[:lower:]')
+
+case "$EXT_LOWER" in
+  png|jpg|jpeg|webp|gif)
+    ;;
+  *)
+    echo "Error: Unsupported image format: .$EXT_LOWER (expected png, jpg, jpeg, webp, or gif)" >&2
+    exit 1
+    ;;
+esac
+
+# Encode to base64 — macOS and Linux compatible
+# macOS base64 doesn't support --wrap, uses -b 0 instead
+if base64 --wrap=0 "$IMAGE_PATH" 2>/dev/null; then
+  : # Linux: --wrap=0 disables line wrapping
+else
+  base64 -i "$IMAGE_PATH" # macOS: no wrapping by default with -i
+fi

package/skills/stitch-nextjs-components/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: stitch-nextjs-components
+description: Converts Stitch designs into production-ready Next.js 15 App Router components — Server vs Client split, dark mode via CSS variables, TypeScript strict, ARIA, and responsive mobile-first layout.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# Stitch → Next.js 15 App Router Components
+
+You are a senior Next.js engineer. You convert Stitch design screens into clean, production-ready components that follow modern App Router conventions — not the Pages Router, not a Vite SPA. Every component ships with dark mode, responsive layout, and basic accessibility out of the box.
+
+## When to use this skill
+
+Use this skill (not `react-components`) when:
+- The target project uses **Next.js 13+** with the **App Router** (`app/` directory)
+- The user mentions `next.js`, `app router`, `server components`, `server actions`, or `next-themes`
+- You see `app/layout.tsx`, `app/page.tsx`, or a `next.config.*` file in the project
+
+## Prerequisites
+
+- Access to the Stitch MCP server
+- A Stitch project with at least one generated screen
+- Target project has `next-themes` installed for dark mode (or user approves adding it)
+
+## Step 1: Retrieve the Stitch design
+
+1. **Namespace discovery** — Run `list_tools` to find the Stitch MCP prefix (e.g., `stitch:`). Use this prefix for all subsequent calls.
+2. **Fetch screen metadata** — Call `[prefix]:get_screen` with the `projectId` and `screenId`.
+3. **Download HTML** — GCS URLs need a reliable downloader:
+   ```bash
+   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
+   ```
+4. **Visual audit** — Check `screenshot.downloadUrl` to understand layout intent before writing code.
+
+## Step 2: Decide Server Component vs Client Component
+
+Apply this decision tree **per component**, not per file:
+
+| Has... | Use |
+|--------|-----|
+| `onClick`, `onChange`, `useState`, `useEffect`, animations | `'use client'` |
+| Only renders data, no interactivity | Server Component (no directive needed) |
+| Wraps a Client Component library | `'use client'` |
+| Form with Server Action | Server Component + `<form action={serverAction}>` |
+
+**Default to Server Components.** Only add `'use client'` when required. This is the single most impactful App Router pattern.
+
+## Step 3: Component architecture
+
+### File structure
+
+```
+app/
+├── [route]/
+│   ├── page.tsx              ← Server Component (route entry)
+│   └── components/
+│       ├── [Name].tsx        ← Logic-heavy Client Component
+│       ├── [Name].module.css ← Scoped styles (optional)
+│       └── index.ts          ← Re-exports
+src/
+├── components/
+│   └── ui/                   ← Reusable primitives
+├── data/
+│   └── mockData.ts           ← Static content decoupled from components
+└── types/
+    └── index.ts              ← Shared TypeScript types
+```
+
+### Rules
+
+- **Props contract**: Every component has a `Readonly<ComponentNameProps>` interface at the top of the file.
+- **Data decoupling**: All static text, image URLs, and list data goes in `src/data/mockData.ts`. Components receive data via props.
+- **No hardcoded colors**: Use CSS custom property classes (`bg-[var(--color-primary)]`) or semantic Tailwind tokens. Never use arbitrary hex in JSX.
+- **No inline styles**: Exceptions only for truly dynamic values (e.g., width from JS calculation).
+
+## Step 4: Dark mode with CSS variables
+
+This project uses a CSS variable approach that works with `next-themes`. Extract colors from the Stitch design and map them to semantic tokens.
+
+In `app/globals.css`:
+```css
+:root {
+  --color-background: #ffffff;
+  --color-surface: #f4f4f5;
+  --color-primary: /* dominant action color from Stitch design */;
+  --color-primary-foreground: #ffffff;
+  --color-text: #09090b;
+  --color-text-muted: #71717a;
+  --color-border: #e4e4e7;
+}
+
+.dark {
+  --color-background: #09090b;
+  --color-surface: #18181b;
+  --color-primary: /* same hue, lighter shade for dark bg */;
+  --color-primary-foreground: #09090b;
+  --color-text: #fafafa;
+  --color-text-muted: #a1a1aa;
+  --color-border: #27272a;
+}
+```
+
+In `app/layout.tsx`, wrap with `ThemeProvider` from `next-themes`:
+```tsx
+import { ThemeProvider } from 'next-themes'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+## Step 5: Responsive layout
+
+All components must work at `sm` (640px), `md` (768px), `lg` (1024px), and `xl` (1280px) breakpoints.
+
+Apply these patterns from the Stitch design:
+- **Navigation**: `hidden md:flex` for desktop nav, `flex md:hidden` for mobile hamburger
+- **Grid**: `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3` — start single column
+- **Typography**: `text-2xl md:text-4xl` — scale up on larger screens
+- **Padding**: `px-4 md:px-8 lg:px-16` — breathe more at wider widths
+- **Images**: Always use `next/image` with `sizes` attribute to avoid CLS
+
+## Step 6: Accessibility baseline
+
+Every component must include these without being asked:
+
+- **Semantic HTML**: `<nav>`, `<main>`, `<section>`, `<article>`, `<header>`, `<footer>` — never a `<div>` when a semantic element fits.
+- **Interactive elements**: Buttons use `<button>`, not `<div onClick>`. Links use `<a>` or `next/link`.
+- **Images**: `<Image>` always has a descriptive `alt` attribute. Decorative images get `alt=""`.
+- **ARIA labels**: Icon-only buttons get `aria-label`. Landmark regions get `aria-label` when there are multiples.
+- **Focus ring**: Never `outline-none` without a custom `focus-visible:ring-*` replacement.
+- **Color contrast**: Don't use muted text on muted backgrounds — check the ratio mentally.
+
+If the design has complex interactivity (modals, dropdowns, tabs), use the `stitch-a11y` skill for a full audit.
+
+## Step 7: Execution steps
+
+1. **Environment check** — If `node_modules` is missing, run `npm install`.
+2. **Data layer** — Create `src/data/mockData.ts` from design content.
+3. **Component drafting** — Use `resources/component-template.tsx` as the starting point. Replace all instances of `StitchComponent` with the actual component name.
+4. **Dark mode tokens** — Add CSS variable declarations to `app/globals.css`. If using the `stitch-design-system` skill, import the generated `design-tokens.css` instead.
+5. **Application wiring** — Update `app/page.tsx` or the relevant route page to import and render the new components.
+6. **Quality check** — Run through `resources/architecture-checklist.md` before declaring done.
+7. **Dev verification** — Run `npm run dev` and check both light and dark modes.
+
+## Step 8: Animation (optional)
+
+If the Stitch design contains clear motion intent (hover states, transitions, reveals), use the `stitch-animate` skill after components are built. Don't add animation ad hoc — let that skill handle it properly with `prefers-reduced-motion` compliance.
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `fetch` fails on GCS URL | Always quote the URL in bash: `bash scripts/fetch-stitch.sh "$URL" out.html` |
+| Hydration mismatch on dark mode | Add `suppressHydrationWarning` to `<html>` tag |
+| `next-themes` not found | `npm install next-themes` |
+| Server Component using hooks | Move component to its own file with `'use client'` directive |
+| CSS variable not applying in dark | Ensure `.dark` class is on `<html>`, not `<body>` |
+
+## Integration with other skills
+
+- **stitch-design-system** — Run first to generate `design-tokens.css`. Import in `globals.css`.
+- **stitch-animate** — Run after to add motion to the generated components.
+- **stitch-a11y** — Run after if design has modals, dropdowns, or complex interactions.
+
+## References
+
+- `resources/component-template.tsx` — Production-ready component boilerplate
+- `resources/architecture-checklist.md` — Pre-ship quality checklist
+- `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader

package/skills/stitch-nextjs-components/resources/architecture-checklist.md

@@ -0,0 +1,65 @@
+# Next.js Components — Architecture Checklist
+
+Run through this checklist before marking the task complete.
+
+## Structure
+
+- [ ] Components are in separate files — no single-file spaghetti
+- [ ] Static content is in `src/data/mockData.ts`, not hardcoded in JSX
+- [ ] Shared TypeScript types are in `src/types/index.ts`
+- [ ] Each component file has a `Readonly<ComponentNameProps>` interface
+- [ ] Custom hooks (if any) are in `src/hooks/`
+
+## App Router correctness
+
+- [ ] Pages are in `app/[route]/page.tsx`, not `pages/`
+- [ ] Interactive components have `'use client'` at the top
+- [ ] Non-interactive components do NOT have `'use client'`
+- [ ] No `useState` / `useEffect` in Server Components
+- [ ] `next/image` used for all images (never `<img>`)
+- [ ] `next/link` used for all internal navigation (never `<a>`)
+
+## TypeScript
+
+- [ ] No `any` types
+- [ ] All function parameters are typed
+- [ ] All component props use `Readonly<>`
+- [ ] No `@ts-ignore` or `@ts-expect-error` without a comment explaining why
+
+## Styling — CSS variables
+
+- [ ] No hardcoded hex colors in JSX or CSS
+- [ ] All colors reference `var(--color-*)` tokens
+- [ ] Dark mode works — toggle `.dark` class on `<html>` and verify visually
+- [ ] `design-tokens.css` is imported in `globals.css`
+
+## Responsive
+
+- [ ] Layout works at 320px (small mobile) — no horizontal overflow
+- [ ] Layout works at 768px (tablet)
+- [ ] Layout works at 1280px (desktop)
+- [ ] Navigation collapses appropriately on mobile
+- [ ] All images have correct `sizes` attribute for responsive loading
+
+## Accessibility baseline
+
+- [ ] Semantic HTML: `<nav>`, `<main>`, `<section>`, `<article>` where appropriate
+- [ ] `<main id="main-content">` exists on every page
+- [ ] Skip navigation link is first element in `app/layout.tsx`
+- [ ] All interactive elements are `<button>` or `<a>`, not `<div>`
+- [ ] All images have descriptive `alt` text (or `alt=""` for decorative)
+- [ ] Icon-only buttons have `aria-label`
+- [ ] No `outline-none` without a visible `focus-visible:ring-*` replacement
+
+## Dark mode
+
+- [ ] `ThemeProvider` is wrapping `{children}` in `app/layout.tsx`
+- [ ] `suppressHydrationWarning` is on the `<html>` tag
+- [ ] Both light and dark modes look correct (test by toggling class)
+- [ ] No elements that "disappear" in dark mode (white on white, etc.)
+
+## Performance
+
+- [ ] No `console.log` statements left in production code
+- [ ] Images use `next/image` with `width` and `height` (or `fill` + `sizes`)
+- [ ] Heavy dependencies are dynamically imported if not needed on initial load

package/skills/stitch-nextjs-components/resources/component-template.tsx

@@ -0,0 +1,101 @@
+/**
+ * StitchComponent
+ *
+ * Generated from Stitch design via stitch-nextjs-components skill.
+ * Replace "StitchComponent" with the actual component name throughout.
+ *
+ * Pattern: Server Component by default.
+ * Add 'use client' only if this component uses hooks, onClick, or browser APIs.
+ */
+
+// Uncomment if this component needs interactivity:
+// 'use client'
+
+import type { ReactNode } from 'react'
+
+// ------------------------------------------------------------
+// Types
+// ------------------------------------------------------------
+
+/**
+ * Props for StitchComponent.
+ * All data comes through props — never imported directly.
+ * Use Readonly<> to prevent accidental mutation.
+ */
+interface StitchComponentProps {
+  /** Primary content to display */
+  title: string
+  /** Supporting description text */
+  description?: string
+  /** Nested content — use for compound components */
+  children?: ReactNode
+  /** Callback for primary action — triggers 'use client' if needed */
+  // onAction?: () => void
+}
+
+// ------------------------------------------------------------
+// Component
+// ------------------------------------------------------------
+
+/**
+ * StitchComponent — [describe what this component does in one sentence]
+ *
+ * @param props - {@link StitchComponentProps}
+ */
+export function StitchComponent({
+  title,
+  description,
+  children,
+}: Readonly<StitchComponentProps>) {
+  return (
+    <section
+      // Semantic landmark — adjust to article, aside, div, etc. as appropriate
+      aria-labelledby="stitch-component-title"
+      className="
+        /* Layout */
+        flex flex-col gap-4
+        /* Spacing */
+        p-6 md:p-8
+        /* Colors — always use CSS variable classes, never arbitrary hex */
+        bg-[var(--color-surface)]
+        text-[var(--color-text)]
+        /* Geometry */
+        rounded-[var(--radius-lg)]
+        border border-[var(--color-border)]
+        /* Shadow */
+        shadow-sm
+        /* Responsive */
+        w-full max-w-2xl
+      "
+    >
+      {/* Heading — maintain hierarchy (h1 → h2 → h3, never skip) */}
+      <h2
+        id="stitch-component-title"
+        className="
+          text-2xl font-bold
+          text-[var(--color-text)]
+          font-[var(--font-sans)]
+        "
+      >
+        {title}
+      </h2>
+
+      {/* Description — optional, use text-muted for supporting copy */}
+      {description && (
+        <p className="text-[var(--color-text-muted)] text-base leading-relaxed">
+          {description}
+        </p>
+      )}
+
+      {/* Slot for nested content */}
+      {children && (
+        <div className="flex flex-col gap-3">
+          {children}
+        </div>
+      )}
+    </section>
+  )
+}
+
+// Default export for page-level components. Named export for UI primitives.
+export default StitchComponent

package/skills/stitch-nextjs-components/scripts/fetch-stitch.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# fetch-stitch.sh
+# Reliably downloads Stitch HTML from Google Cloud Storage URLs.
+# GCS URLs require redirect handling and specific security handshakes that
+# AI fetch tools often fail on. This script handles both.
+#
+# Usage:
+#   bash scripts/fetch-stitch.sh "<url>" "<output-path>"
+#
+# Example:
+#   bash scripts/fetch-stitch.sh "$htmlCode_downloadUrl" "temp/source.html"
+
+set -euo pipefail
+
+URL="${1:?Usage: fetch-stitch.sh <url> <output-path>}"
+OUTPUT="${2:?Usage: fetch-stitch.sh <url> <output-path>}"
+
+# Create output directory if it doesn't exist
+mkdir -p "$(dirname "$OUTPUT")"
+
+# Use curl with:
+#   -L  : follow redirects (GCS uses multiple redirect hops)
+#   -A  : set User-Agent to avoid bot blocking
+#   --compressed : handle gzip responses
+#   --retry 3   : retry on transient failures
+#   --retry-delay 1 : wait 1s between retries
+#   --max-time 30   : don't hang forever
+curl -L \
+  -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
+  --compressed \
+  --retry 3 \
+  --retry-delay 1 \
+  --max-time 30 \
+  --silent \
+  --show-error \
+  --output "$OUTPUT" \
+  "$URL"
+
+# Verify the download succeeded and is not empty
+if [ ! -s "$OUTPUT" ]; then
+  echo "Error: Downloaded file is empty. URL may be expired or invalid." >&2
+  exit 1
+fi
+
+echo "Downloaded to: $OUTPUT ($(wc -c < "$OUTPUT") bytes)"