Plans: plan and scans in Subscription, one upgrade prompt for every limit

CLAUDE.md

@@ -17,6 +17,8 @@ Connected mode uses the existing ScribbleScan API only through `/v1`. Response t
 
 Sign-in (`app/connect/page.tsx`) is passwordless: **Continue with email** (a code, or the link in the email), **Google** and **Apple**, through `/v1/auth/*`. The page makes the PKCE verifier (`oidc.begin()`, kept in localStorage so the emailed link works in a new tab), the API runs the sign-in with Zitadel, and the browser lands on `/?code=...`, which the app shell hands to `/connect` for `oidc.finish()`. `GET /v1/config`'s `login_methods` says which choices work; empty with `auth: "oidc"` means Zitadel's hosted pages, and dev mode signs in from the email step without a code.
 
+Plans (`src/plan.ts`): the API answers `402 {code: "upgrade_required", feature, plan, message}` when something needs a bigger plan. `apiError()` in `src/api/client.ts` turns that into the `ss:upgrade` event, and the one `UpgradeDialog` (mounted in the app shell) shows the plans from `GET /v1/plan`. Use `apiError()` for any failed request so every limit reaches the same prompt. Until payments exist, upgrading is an email to `upgrade_contact`.
+
 The phone pairing secret belongs only in the scan URL fragment. QR SVGs must come from `POST /v1/qr`, never from a URL containing the secret.
 
 ## Commands

app/receipts/page.tsx

@@ -2,7 +2,7 @@
 
 import Link from "next/link";
 import { useEffect, useMemo, useState } from "react";
-import { request } from "@/src/api/client";
+import { apiError, request } from "@/src/api/client";
 import { useDemo } from "@/src/components/demo-context";
 import { MonthNav } from "@/src/components/month-nav";
 import { monthLabel } from "@/src/format";
@@ -37,7 +37,8 @@ export default function ReceiptsPage() {
     setExportError("");
     try {
       const response = await request(`/v1/spaces/${activeSpaceId}/export?month=${month}&format=xlsx`);
-      if (!response.ok) throw new Error("Export failed. Try again.");
+      if (!response.ok)
+        throw response.status === 402 ? await apiError(response) : new Error("Export failed. Try again.");
       const blob = await response.blob();
       const url = URL.createObjectURL(blob);
       const anchor = document.createElement("a");