@agent-native/core 0.79.26 → 0.80.0

package/corpus/templates/calendar/app/i18n/zh-TW.ts

@@ -149,6 +149,8 @@ const messages = {
       "已從 Google Calendar 同步 {{count}} 個事件",
   },
   sidebar: {
+    collapseSidebar: "收合側邊欄",
+    expandSidebar: "展開側邊欄",
     addGoogleAccount: "新增 Google 帳號",
     colorByMeetingType: "按會議型別著色（外部、內部、一對一、小組等）",
     googleCalendarSettings: "Google Calendar 設定",

package/corpus/templates/calendar/app/i18n-data.ts

@@ -161,6 +161,8 @@ const enUS = {
       "Synced {{count}} events from Google Calendar",
   },
   sidebar: {
+    collapseSidebar: "Collapse sidebar",
+    expandSidebar: "Expand sidebar",
     addGoogleAccount: "Add Google account",
     colorByMeetingType:
       "Color by meeting type (external, internal, 1:1, group, etc.)",
@@ -6133,6 +6135,8 @@ const translatedCalendarRemainingRaw = {
         "已从 Google Calendar 同步 {{count}} 个事件",
     },
     sidebar: {
+      collapseSidebar: "折叠侧边栏",
+      expandSidebar: "展开侧边栏",
       addGoogleAccount: "添加 Google 账号",
       colorByMeetingType: "按会议类型着色（外部、内部、一对一、小组等）",
       googleCalendarSettings: "Google Calendar 设置",
@@ -6254,6 +6258,8 @@ const translatedCalendarRemainingRaw = {
         "{{count}} eventos sincronizados desde Google Calendar",
     },
     sidebar: {
+      collapseSidebar: "Contraer barra lateral",
+      expandSidebar: "Expandir barra lateral",
       addGoogleAccount: "Añadir cuenta de Google",
       colorByMeetingType:
         "Color por tipo de reunión (externa, interna, 1:1, grupo, etc.)",
@@ -6592,6 +6598,8 @@ const translatedCalendarExactCleanup = {
         "{{count}} événements synchronisés depuis Google Calendar",
     },
     sidebar: {
+      collapseSidebar: "Réduire la barre latérale",
+      expandSidebar: "Développer la barre latérale",
       addGoogleAccount: "Ajouter un compte Google",
       colorByMeetingType:
         "Couleur par type de réunion (externe, interne, 1:1, groupe, etc.)",
@@ -6772,6 +6780,8 @@ const translatedCalendarExactCleanup = {
         "{{count}} Termine aus Google Calendar synchronisiert",
     },
     sidebar: {
+      collapseSidebar: "Seitenleiste einklappen",
+      expandSidebar: "Seitenleiste erweitern",
       addGoogleAccount: "Google-Konto hinzufügen",
       colorByMeetingType:
         "Nach Meetingtyp einfärben (extern, intern, 1:1, Gruppe usw.)",
@@ -6941,6 +6951,8 @@ const translatedCalendarExactCleanup = {
         "Google Calendar から {{count}} 件の予定を同期しました",
     },
     sidebar: {
+      collapseSidebar: "サイドバーを折りたたむ",
+      expandSidebar: "サイドバーを展開",
       addGoogleAccount: "Google アカウントを追加",
       colorByMeetingType:
         "会議タイプ別に色分け (外部、内部、1:1、グループなど)",
@@ -7106,6 +7118,8 @@ const translatedCalendarExactCleanup = {
         "Google Calendar에서 이벤트 {{count}}개 동기화됨",
     },
     sidebar: {
+      collapseSidebar: "사이드바 접기",
+      expandSidebar: "사이드바 펼치기",
       addGoogleAccount: "Google 계정 추가",
       colorByMeetingType: "회의 유형별 색상 지정(외부, 내부, 1:1, 그룹 등)",
       googleCalendarSettings: "Google Calendar 설정",
@@ -7285,6 +7299,8 @@ const translatedCalendarExactCleanup = {
         "{{count}} eventos sincronizados do Google Calendar",
     },
     sidebar: {
+      collapseSidebar: "Recolher barra lateral",
+      expandSidebar: "Expandir barra lateral",
       addGoogleAccount: "Adicionar conta Google",
       colorByMeetingType:
         "Colorir por tipo de reunião (externa, interna, 1:1, grupo etc.)",
@@ -7452,6 +7468,8 @@ const translatedCalendarExactCleanup = {
       syncedFromGoogleCalendar_other: "Google Calendar से {{count}} इवेंट सिंक हुए",
     },
     sidebar: {
+      collapseSidebar: "साइडबार समेटें",
+      expandSidebar: "साइडबार फैलाएं",
       addGoogleAccount: "Google खाता जोड़ें",
       colorByMeetingType: "मीटिंग प्रकार से रंग दें (बाहरी, आंतरिक, 1:1, समूह आदि)",
       googleCalendarSettings: "Google Calendar सेटिंग",
@@ -7634,6 +7652,8 @@ const translatedCalendarExactCleanup = {
         "تمت مزامنة {{count}} حدث من Google Calendar",
     },
     sidebar: {
+      collapseSidebar: "طي الشريط الجانبي",
+      expandSidebar: "توسيع الشريط الجانبي",
       addGoogleAccount: "إضافة حساب Google",
       colorByMeetingType:
         "التلوين حسب نوع الاجتماع (خارجي، داخلي، 1:1، مجموعة، إلخ)",

package/corpus/templates/calendar/changelog/2026-06-28-left-sidebar-collapses-into-an-animated-icon-rail.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-28
+---
+
+The left sidebar now collapses into an animated icon rail with quieter footer controls.

package/corpus/templates/chat/app/components/layout/Sidebar.tsx

@@ -442,7 +442,7 @@ export function Sidebar({
     <aside
       data-collapsed={collapsed ? "true" : "false"}
       className={cn(
-        "flex h-full min-w-0 shrink-0 flex-col overflow-hidden border-e border-sidebar-border bg-sidebar text-sidebar-foreground transition-[width] duration-150",
+        "flex h-full min-w-0 shrink-0 flex-col overflow-hidden border-e border-sidebar-border bg-sidebar text-sidebar-foreground transition-[width] duration-200 ease-out",
         collapsed ? "w-12" : "w-60",
       )}
     >
@@ -540,25 +540,14 @@ export function Sidebar({
         </div>
       </nav>
 
-      <div
-        className={cn(
-          "mt-auto shrink-0",
-          collapsed && "border-t border-sidebar-border py-2",
-        )}
-      >
+      <div className={cn("mt-auto shrink-0", collapsed && "py-2")}>
         {!collapsed ? (
-          <div className="border-t border-sidebar-border px-2 py-1">
+          <div className="px-2 py-1">
             <ExtensionsSidebarSection />
           </div>
         ) : null}
 
-        <div
-          className={cn(
-            collapsed
-              ? "px-1 py-1"
-              : "border-t border-sidebar-border px-3 py-2",
-          )}
-        >
+        <div className={cn(collapsed ? "px-1 py-1" : "px-3 py-2")}>
           <OrgSwitcher
             reserveSpace
             className={
@@ -571,9 +560,7 @@ export function Sidebar({
 
         <div
           className={cn(
-            collapsed
-              ? "flex justify-center px-1 py-1"
-              : "border-t border-sidebar-border px-3 py-2",
+            collapsed ? "flex justify-center px-1 py-1" : "px-3 py-2",
           )}
         >
           <FeedbackButton
@@ -588,7 +575,7 @@ export function Sidebar({
             className={cn(
               collapsed
                 ? "flex justify-center px-1 py-1"
-                : "flex justify-end border-t border-sidebar-border px-3 py-2",
+                : "flex justify-end px-3 py-2",
             )}
           >
             {collapseButton}

package/corpus/templates/chat/changelog/2026-06-28-left-sidebar-collapse-motion-and-footer-chrome-are-quieter.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-28
+---
+
+Left sidebar collapse motion and footer controls now feel smoother and use less divider chrome.

package/corpus/templates/clips/AGENTS.md

@@ -25,6 +25,10 @@ Detailed media, meeting, dictation, editing, and sharing rules live in
   download the original from Loom and use "Upload video".
 - Native transcript first. Cleanup and title generation can run in the
   background; do not hide a usable native transcript behind a failed cleanup.
+- Dictation cleanup, Clip title/cleanup, and meeting summaries should pass
+  bounded `voiceContext` to the shared cleanup/transcription path when active
+  app context, learned vocabulary, user notes, or AGENTS.md preferences are
+  available.
 - Cloud transcription is fallback-only for Clips recordings and should use the
   configured Builder/Gemini or Groq paths, not OpenAI.
 - AI setup must be visible and paid-account-backed: lead with Builder.io Connect
@@ -60,6 +64,10 @@ Detailed media, meeting, dictation, editing, and sharing rules live in
   tell the user that clearly and point them to Builder.io credits/upgrade or a
   Groq key for backup speech-to-text. Generic OpenAI or Anthropic chat keys do
   not transcribe Clips recordings.
+- Use `get-builder-credit-status` when the user asks whether Builder.io credit
+  limits are pausing backup transcription, transcript cleanup, summaries, or AI
+  title generation. Treat an exhausted status as an FYI/upgrade path, not an app
+  error.
 - Slack unfurls use `/api/slack/unfurl` for `link_shared` events and only
   return playable `chat.unfurl` video blocks for ready public clips with no
   password, no expiry hit, and no archive/trash marker. Private, org-only,

package/corpus/templates/clips/actions/cleanup-transcript.ts

@@ -31,8 +31,19 @@ import {
   resolveSecret,
   FeatureNotConfiguredError,
 } from "@agent-native/core/server";
+import {
+  applyVoiceContextReplacements,
+  formatVoiceContextPackForPrompt,
+  type VoiceContextPack,
+} from "@agent-native/core/voice";
 import { z } from "zod";
 
+import { isBuilderCreditsExhaustedMessage } from "../shared/builder-credits.js";
+import {
+  clearBuilderCreditsExhausted,
+  noteBuilderCreditsExhausted,
+} from "./lib/builder-credits-state.js";
+
 // Builder gateway maps this to Gemini 3.1 Flash-Lite (see transcribe-voice.ts:52).
 const BUILDER_MODEL = "gemini-3-1-flash-lite";
 
@@ -84,6 +95,12 @@ export default defineAction({
       .describe(
         "Optional surrounding context (e.g. meeting title, attendees, previous notes) to ground the cleanup pass.",
       ),
+    contextPack: z
+      .unknown()
+      .optional()
+      .describe(
+        "Optional structured voice context: snippets, vocabulary replacements, and metadata.",
+      ),
     language: z
       .string()
       .optional()
@@ -91,10 +108,12 @@ export default defineAction({
   }),
   run: async (args): Promise<CleanupResult> => {
     const transcript = args.transcript.slice(0, MAX_INPUT_CHARS);
+    const contextPack = args.contextPack as VoiceContextPack | undefined;
     const prompt = buildPrompt({
       task: args.task,
       transcript,
       context: args.context,
+      contextPack,
       language: args.language,
     });
     const wantJson = args.task === "summary";
@@ -117,7 +136,8 @@ export default defineAction({
           wantJson,
         });
         if (text.trim()) {
-          return shapeResult(args.task, text, "builder");
+          await clearBuilderCreditsExhausted();
+          return shapeResult(args.task, text, "builder", contextPack);
         }
         builderReturnedEmpty = true;
         console.warn("[cleanup-transcript] Builder path returned empty text");
@@ -126,7 +146,18 @@ export default defineAction({
         // Hard errors (e.g. credits exhausted) still surface to the caller.
         const message = (err as Error)?.message ?? String(err);
         builderFailureMessage = message;
-        if (message.includes("credits exhausted")) throw err;
+        if (isBuilderCreditsExhaustedMessage(message)) {
+          await noteBuilderCreditsExhausted({
+            source:
+              args.task === "title"
+                ? "title"
+                : args.task === "summary"
+                  ? "summary"
+                  : "cleanup",
+            message,
+          });
+          throw err;
+        }
         console.warn("[cleanup-transcript] Builder path failed:", message);
       }
     }
@@ -139,7 +170,7 @@ export default defineAction({
         prompt,
         wantJson,
       });
-      return shapeResult(args.task, text, "gemini-byok");
+      return shapeResult(args.task, text, "gemini-byok", contextPack);
     }
 
     throw buildCleanupConfigurationError({
@@ -299,13 +330,16 @@ function shapeResult(
   task: "cleanup" | "title" | "summary",
   raw: string,
   provider: "builder" | "gemini-byok",
+  contextPack?: VoiceContextPack,
 ): CleanupResult {
   const stripped = stripEnvelope(raw);
+  const applyContext = (value: string) =>
+    applyVoiceContextReplacements(value, contextPack).trim();
   if (task === "title") {
-    return { task, title: stripped.slice(0, 120), provider };
+    return { task, title: applyContext(stripped).slice(0, 120), provider };
   }
   if (task === "cleanup") {
-    return { task, cleanedText: stripped, provider };
+    return { task, cleanedText: applyContext(stripped), provider };
   }
   // task === 'summary' — expect JSON.
   try {
@@ -320,11 +354,16 @@ function shapeResult(
     };
     return {
       task,
-      summaryMd: typeof parsed.summaryMd === "string" ? parsed.summaryMd : "",
+      summaryMd:
+        typeof parsed.summaryMd === "string"
+          ? applyContext(parsed.summaryMd)
+          : "",
       bullets: Array.isArray(parsed.bullets)
         ? parsed.bullets
             .map((b) =>
-              typeof b === "string" ? { text: b } : { text: b.text ?? "" },
+              typeof b === "string"
+                ? { text: applyContext(b) }
+                : { text: applyContext(b.text ?? "") },
             )
             .filter((b) => b.text)
         : [],
@@ -341,7 +380,7 @@ function shapeResult(
                   : "";
               const isEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(rawEmail);
               return {
-                text: (a.text ?? "").trim(),
+                text: applyContext(a.text ?? ""),
                 ...(isEmail ? { assigneeEmail: rawEmail } : {}),
                 ...(a.dueDate ? { dueDate: a.dueDate } : {}),
               };
@@ -353,7 +392,7 @@ function shapeResult(
     // Provider didn't return JSON — fall back to raw markdown summary.
     return {
       task,
-      summaryMd: stripped,
+      summaryMd: applyContext(stripped),
       bullets: [],
       actionItems: [],
       provider,
@@ -373,15 +412,24 @@ function buildPrompt({
   task,
   transcript,
   context,
+  contextPack,
   language,
 }: {
   task: "cleanup" | "title" | "summary";
   transcript: string;
   context?: string;
+  contextPack?: VoiceContextPack;
   language?: string;
 }): { system: string; user: string } {
   const langHint = language ? ` The transcript language is ${language}.` : "";
-  const ctxBlock = context ? `\n\n<context>\n${context}\n</context>` : "";
+  const voiceContext = formatVoiceContextPackForPrompt(contextPack);
+  const contextParts = [
+    context?.trim(),
+    voiceContext ? `Voice context:\n${voiceContext}` : "",
+  ].filter(Boolean);
+  const ctxBlock = contextParts.length
+    ? `\n\n<context>\n${contextParts.join("\n\n")}\n</context>`
+    : "";
 
   if (task === "title") {
     return {

package/corpus/templates/clips/actions/finalize-meeting.ts

@@ -13,12 +13,20 @@
 import { defineAction } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { assertAccess } from "@agent-native/core/sharing";
+import type { VoiceContextPack } from "@agent-native/core/voice";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { nanoid } from "../server/lib/recordings.js";
 import cleanupTranscript, { CleanupResult } from "./cleanup-transcript.js";
+import { loadAgentsMdContext } from "./lib/agents-md-context.js";
+
+function trimContextValue(value: string, maxChars: number): string {
+  const trimmed = value.replace(/\0/g, "").trim();
+  if (trimmed.length <= maxChars) return trimmed;
+  return `${trimmed.slice(0, maxChars).trimEnd()}\n[truncated]`;
+}
 
 export default defineAction({
   description:
@@ -72,29 +80,90 @@ export default defineAction({
       .set({ transcriptStatus: "pending", updatedAt: nowIso })
       .where(eq(schema.meetings.id, args.meetingId));
 
-    const participants = await db
-      .select()
-      .from(schema.meetingParticipants)
-      .where(eq(schema.meetingParticipants.meetingId, args.meetingId));
+    const [participants, recordingRows, agentsContext] = await Promise.all([
+      db
+        .select()
+        .from(schema.meetingParticipants)
+        .where(eq(schema.meetingParticipants.meetingId, args.meetingId)),
+      meeting.recordingId
+        ? db
+            .select({
+              title: schema.recordings.title,
+              sourceAppName: schema.recordings.sourceAppName,
+              sourceWindowTitle: schema.recordings.sourceWindowTitle,
+              description: schema.recordings.description,
+            })
+            .from(schema.recordings)
+            .where(eq(schema.recordings.id, meeting.recordingId))
+            .limit(1)
+        : Promise.resolve([]),
+      loadAgentsMdContext({
+        ownerEmail: meeting.ownerEmail,
+        purpose: "summary",
+      }),
+    ]);
+    const linkedRecording = recordingRows[0] ?? null;
 
-    const contextLines: string[] = [];
-    if (meeting.title) contextLines.push(`Meeting: ${meeting.title}`);
+    // Build a single bounded context pack for the summary prompt. Avoid also
+    // emitting the same fields as a parallel plain-text `context` string: the
+    // cleanup prompt concatenates both into one <context> block, so passing
+    // both would duplicate every snippet (and the plain-text path was
+    // unbounded at ~20k chars per field).
+    const contextSnippets: NonNullable<VoiceContextPack["snippets"]> = [];
+    const addSnippet = (label: string, value: string, maxChars = 2_000) => {
+      const trimmed = trimContextValue(value, maxChars);
+      if (trimmed) contextSnippets.push({ label, value: trimmed });
+    };
+    if (meeting.title) addSnippet("Meeting title", meeting.title, 200);
     if (meeting.scheduledStart)
-      contextLines.push(`Scheduled: ${meeting.scheduledStart}`);
+      addSnippet("Scheduled start", meeting.scheduledStart, 120);
     if (participants.length) {
-      contextLines.push(
-        `Attendees: ${participants
-          .map((p) => `${p.name ?? p.email} <${p.email}>`)
-          .join(", ")}`,
+      addSnippet(
+        "Attendees",
+        participants.map((p) => `${p.name ?? p.email} <${p.email}>`).join(", "),
+        1800,
+      );
+    }
+    if (meeting.userNotesMd.trim()) {
+      addSnippet("User notes", meeting.userNotesMd, 3_000);
+    }
+    if (linkedRecording) {
+      addSnippet(
+        "Linked Clip",
+        [
+          linkedRecording.title,
+          linkedRecording.sourceAppName,
+          linkedRecording.sourceWindowTitle,
+          linkedRecording.description,
+        ]
+          .filter(Boolean)
+          .join("\n"),
+        1800,
       );
     }
+    if (agentsContext)
+      addSnippet("AGENTS.md preferences", agentsContext, 3_000);
+    const contextPack: VoiceContextPack | undefined = contextSnippets.length
+      ? {
+          surface: "clips-meeting",
+          mode: "summary",
+          snippets: contextSnippets,
+          metadata: {
+            meetingId: meeting.id,
+            recordingId: meeting.recordingId,
+            calendarEventId: meeting.calendarEventId,
+            source: meeting.source,
+            platform: meeting.platform,
+          },
+        }
+      : undefined;
 
     let result: CleanupResult;
     try {
       result = await cleanupTranscript.run({
         transcript: transcriptText,
         task: "summary",
-        context: contextLines.join("\n") || undefined,
+        contextPack,
       });
     } catch (err) {
       await db

package/corpus/templates/clips/actions/get-builder-credit-status.ts

@@ -0,0 +1,22 @@
+import { defineAction } from "@agent-native/core";
+import { readAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+import {
+  CLIPS_BUILDER_CREDITS_STATE_KEY,
+  normalizeBuilderCreditsStatus,
+} from "../shared/builder-credits.js";
+
+export default defineAction({
+  description:
+    "Return the last known Builder.io AI credit limit state for Clips. Use this before explaining paused backup transcription, transcript cleanup, summaries, or AI title generation.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async () => {
+    const raw = await readAppState(CLIPS_BUILDER_CREDITS_STATE_KEY).catch(
+      () => null,
+    );
+    return normalizeBuilderCreditsStatus(raw);
+  },
+});

package/corpus/templates/clips/actions/get-recording-player-data.ts

@@ -28,6 +28,10 @@ import { getDb, schema } from "../server/db/index.js";
 import { resolvePlayerVideoUrl } from "../server/lib/player-video-url.js";
 import { parseSpaceIds } from "../server/lib/recordings.js";
 import { parseBrowserDiagnosticsRow } from "../shared/browser-diagnostics.js";
+import {
+  CLIPS_BUILDER_CREDITS_STATE_KEY,
+  normalizeBuilderCreditsStatus,
+} from "../shared/builder-credits.js";
 import {
   normalizeTranscriptSegments,
   parseTranscriptSegments,
@@ -106,13 +110,23 @@ export default defineAction({
       .from(schema.recordingTranscripts)
       .where(eq(schema.recordingTranscripts.recordingId, args.recordingId))
       .limit(1);
-    const cleanupStateRaw = await readAppState(
-      `transcript-cleanup-${args.recordingId}`,
-    ).catch(() => null);
+    const canEditRecording =
+      access.role === "owner" ||
+      access.role === "admin" ||
+      access.role === "editor";
+    const [cleanupStateRaw, builderCreditsRaw] = await Promise.all([
+      readAppState(`transcript-cleanup-${args.recordingId}`).catch(() => null),
+      canEditRecording
+        ? readAppState(CLIPS_BUILDER_CREDITS_STATE_KEY).catch(() => null)
+        : Promise.resolve(null),
+    ]);
     const cleanupState =
       cleanupStateRaw && typeof cleanupStateRaw === "object"
         ? (cleanupStateRaw as Record<string, unknown>)
         : null;
+    const builderCredits = canEditRecording
+      ? normalizeBuilderCreditsStatus(builderCreditsRaw)
+      : null;
 
     const comments = await db
       .select()
@@ -296,6 +310,7 @@ export default defineAction({
               : null,
           }
         : null,
+      builderCredits,
       comments: comments.map((c) => ({
         id: c.id,
         recordingId: c.recordingId,

package/corpus/templates/clips/actions/lib/agents-md-context.ts

@@ -5,7 +5,7 @@ import {
 
 const MAX_AGENTS_MD_CONTEXT_CHARS = 60_000;
 
-type AgentsContextPurpose = "title" | "cleanup";
+type AgentsContextPurpose = "title" | "cleanup" | "summary";
 
 function trimAgentsMdContext(content: string): string {
   const trimmed = content.trim();
@@ -31,6 +31,9 @@ function purposeInstruction(purpose: AgentsContextPurpose): string {
   if (purpose === "cleanup") {
     return "Use these AGENTS.md resources only for relevant transcript cleanup preferences: vocabulary, casing, punctuation style, formatting style, terminology, speaker voice, and team/personal conventions. If the personal and organization instructions conflict, prefer the personal instructions.";
   }
+  if (purpose === "summary") {
+    return "Use these AGENTS.md resources only for relevant meeting-summary preferences: vocabulary, casing, terminology, action-item style, formatting style, and team/personal conventions. If the personal and organization instructions conflict, prefer the personal instructions.";
+  }
 
   return "Use these AGENTS.md resources only for relevant Clip naming, terminology, style, and personal/team preferences. If the personal and organization instructions conflict, prefer the personal instructions.";
 }

package/corpus/templates/clips/actions/lib/builder-credits-state.ts

@@ -0,0 +1,46 @@
+import {
+  deleteAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+
+import {
+  CLIPS_BUILDER_CREDITS_STATE_KEY,
+  createBuilderCreditsExhaustedStatus,
+  type BuilderCreditsSource,
+} from "../../shared/builder-credits.js";
+
+export async function noteBuilderCreditsExhausted({
+  source,
+  message,
+}: {
+  source: BuilderCreditsSource;
+  message: string;
+}): Promise<void> {
+  try {
+    await writeAppState(
+      CLIPS_BUILDER_CREDITS_STATE_KEY,
+      createBuilderCreditsExhaustedStatus({
+        source,
+        message,
+      }) as unknown as Record<string, unknown>,
+    );
+    await writeAppState("refresh-signal", { ts: Date.now() });
+  } catch (err) {
+    console.warn(
+      "[clips] failed to record Builder credit state:",
+      (err as Error)?.message ?? String(err),
+    );
+  }
+}
+
+export async function clearBuilderCreditsExhausted(): Promise<void> {
+  try {
+    const removed = await deleteAppState(CLIPS_BUILDER_CREDITS_STATE_KEY);
+    if (removed) await writeAppState("refresh-signal", { ts: Date.now() });
+  } catch (err) {
+    console.warn(
+      "[clips] failed to clear Builder credit state:",
+      (err as Error)?.message ?? String(err),
+    );
+  }
+}