feat: usage quota visualization in AI settings

No user-facing view of AI-call/recipe/storage usage existed — only an
admin-only per-user panel. Adds the same numbers, with progress bars
against the user's actual tier limits (read fresh from the DB, not
the cached session), to Settings > AI.

v0.40.0

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to Epicure are documented here. This file is mirrored in-app at `/changelog` (and in the admin dashboard) via `apps/web/lib/changelog.ts` — update both together.
 
+## 0.40.0 — 2026-07-17 14:00
+
+### Added
+- AI Settings now shows a usage panel — AI calls, recipes created, and storage used this month against your tier's limits, with progress bars.
+
 ## 0.39.0 — 2026-07-17 13:30
 
 ### Fixed

apps/web/app/(app)/settings/ai/page.tsx

@@ -1,10 +1,12 @@
 import type { Metadata } from "next";
 import { headers } from "next/headers";
 import { auth } from "@/lib/auth/server";
-import { db, userAiKeys, userModelPrefs, eq } from "@epicure/db";
+import { db, userAiKeys, userModelPrefs, users, tierDefinitions, userUsage, eq, and } from "@epicure/db";
+import { UNLIMITED } from "@/lib/tiers";
 import { ByokManager } from "@/components/settings/byok-manager";
 import { ModelPrefsForm } from "@/components/settings/model-prefs-form";
-import { getMessages } from "@/lib/i18n/server";
+import { UsageQuotaSection } from "@/components/settings/usage-quota-section";
+import { getMessages, formatMessage } from "@/lib/i18n/server";
 
 export const metadata: Metadata = {};
 
@@ -13,7 +15,9 @@ export default async function AiSettingsPage() {
   if (!session) return null;
   const m = getMessages((session.user as { locale?: string }).locale);
 
-  const [aiKeys, modelPrefs] = await Promise.all([
+  const currentMonth = new Date().toISOString().slice(0, 7);
+
+  const [aiKeys, modelPrefs, dbUser] = await Promise.all([
     db.query.userAiKeys.findMany({
       where: eq(userAiKeys.userId, session.user.id),
       columns: { provider: true },
@@ -21,10 +25,52 @@ export default async function AiSettingsPage() {
     db.query.userModelPrefs.findFirst({
       where: eq(userModelPrefs.userId, session.user.id),
     }),
+    // Tier comes from the DB, not the (up to 5-minute-stale) session cookie
+    // cache, so a just-changed tier's limits show up immediately here.
+    db.query.users.findFirst({ where: eq(users.id, session.user.id), columns: { tier: true } }),
   ]);
 
+  const [tierDef, usage] = await Promise.all([
+    db.query.tierDefinitions.findFirst({ where: eq(tierDefinitions.tier, dbUser?.tier ?? "free") }),
+    db.query.userUsage.findFirst({ where: and(eq(userUsage.userId, session.user.id), eq(userUsage.month, currentMonth)) }),
+  ]);
+
+  const asLimit = (n: number | undefined) => (n === undefined || n === UNLIMITED ? null : n);
+
+  const usageMetrics = [
+    {
+      label: m.settings.usage.aiCalls,
+      used: usage?.aiCallsUsed ?? 0,
+      limit: asLimit(tierDef?.aiCallsPerMonth),
+      unlimitedLabel: m.settings.usage.unlimited,
+    },
+    {
+      label: m.settings.usage.recipes,
+      used: usage?.recipeCount ?? 0,
+      limit: asLimit(tierDef?.maxRecipes),
+      unlimitedLabel: m.settings.usage.unlimited,
+    },
+    {
+      label: m.settings.usage.storage,
+      used: usage?.storageUsedMb ?? 0,
+      limit: asLimit(tierDef?.storageMb),
+      unit: " MB",
+      unlimitedLabel: m.settings.usage.unlimited,
+    },
+  ];
+
   return (
     <div className="space-y-8">
+      <section className="rounded-xl border p-6 space-y-4">
+        <div>
+          <h2 className="font-semibold text-lg">{m.settings.usage.title}</h2>
+          <p className="text-sm text-muted-foreground mt-1">
+            {formatMessage(m.settings.usage.description, { month: currentMonth })}
+          </p>
+        </div>
+        <UsageQuotaSection metrics={usageMetrics} />
+      </section>
+
       <section className="rounded-xl border p-6 space-y-4">
         <div>
           <h2 className="font-semibold text-lg">{m.settings.byok.title}</h2>

apps/web/components/settings/usage-quota-section.tsx

@@ -0,0 +1,35 @@
+import { Progress } from "@/components/ui/progress";
+
+type UsageMetric = {
+  label: string;
+  used: number;
+  limit: number | null;
+  unit?: string;
+  unlimitedLabel: string;
+};
+
+function UsageBar({ label, used, limit, unit, unlimitedLabel }: UsageMetric) {
+  const pct = limit === null ? 0 : Math.min(100, (used / Math.max(limit, 1)) * 100);
+  return (
+    <div className="space-y-1.5">
+      <div className="flex justify-between text-sm">
+        <span className="text-muted-foreground">{label}</span>
+        <span className="font-medium tabular-nums">
+          {used}
+          {unit} / {limit === null ? unlimitedLabel : `${limit}${unit ?? ""}`}
+        </span>
+      </div>
+      {limit !== null && <Progress value={pct} />}
+    </div>
+  );
+}
+
+export function UsageQuotaSection({ metrics }: { metrics: UsageMetric[] }) {
+  return (
+    <div className="space-y-4">
+      {metrics.map((m) => (
+        <UsageBar key={m.label} {...m} />
+      ))}
+    </div>
+  );
+}

apps/web/lib/changelog.ts

@@ -1,5 +1,5 @@
 // Mirrors CHANGELOG.md at the repo root — update both together.
-export const APP_VERSION = "0.39.0";
+export const APP_VERSION = "0.40.0";
 
 export type ChangelogEntry = {
   version: string;
@@ -11,6 +11,13 @@ export type ChangelogEntry = {
 };
 
 export const CHANGELOG: ChangelogEntry[] = [
+  {
+    version: "0.40.0",
+    date: "2026-07-17 14:00",
+    added: [
+      "AI Settings now shows a usage panel — AI calls, recipes created, and storage used this month against your tier's limits, with progress bars.",
+    ],
+  },
   {
     version: "0.39.0",
     date: "2026-07-17 13:30",

apps/web/messages/en.json

@@ -325,6 +325,14 @@
     "nutrition": "Nutrition",
     "apiKeys": "API Keys",
     "webhooks": "Webhooks",
+    "usage": {
+      "title": "Usage this month",
+      "description": "Resets at the start of each month ({month}).",
+      "aiCalls": "AI calls",
+      "recipes": "Recipes created",
+      "storage": "Storage",
+      "unlimited": "Unlimited"
+    },
     "byok": {
       "title": "Your API Keys (BYOK)",
       "description": "Use your own API keys instead of the app's shared quota. Keys are encrypted at rest."

apps/web/messages/fr.json

@@ -325,6 +325,14 @@
     "nutrition": "Nutrition",
     "apiKeys": "Clés API",
     "webhooks": "Webhooks",
+    "usage": {
+      "title": "Utilisation ce mois-ci",
+      "description": "Réinitialisé au début de chaque mois ({month}).",
+      "aiCalls": "Appels IA",
+      "recipes": "Recettes créées",
+      "storage": "Stockage",
+      "unlimited": "Illimité"
+    },
     "byok": {
       "title": "Vos clés API (BYOK)",
       "description": "Utilisez vos propres clés API au lieu du quota partagé de l'application. Les clés sont chiffrées au repos."

apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicure/web",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "private": true,
   "scripts": {
     "dev": "next dev",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicure",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "private": true,
   "scripts": {
     "dev": "pnpm --filter web dev",