@agent-native/core 0.92.10 → 0.92.12

package/corpus/core/src/client/rich-markdown-editor/useCollabReconcile.ts

@@ -385,6 +385,8 @@ export function useCollabReconcile({
       const editorUnchangedSinceApply =
         lastAppliedSerializedRef.current !== null &&
         currentMarkdown === lastAppliedSerializedRef.current;
+      const typingRecently =
+        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
 
       // Doc-equivalence skip. Never re-apply content the editor already
       // represents — comparing by DOC EQUIVALENCE, not raw strings/timestamps:
@@ -407,11 +409,15 @@ export function useCollabReconcile({
       //      `<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` escalation.
       if (
         currentMarkdown === normalizedValue ||
-        value === lastEmittedRef.current ||
-        // A stale-but-recent echo of our own (possibly partial) save — applying
-        // it would clobber the freshly-typed tail. External edits never match.
-        recentEmittedRef.current.includes(value) ||
-        recentEmittedRef.current.includes(normalizedValue) ||
+        (typingRecently &&
+          // A stale echo of our own (possibly partial) save while the user is
+          // actively typing would clobber the fresh tail. Outside active
+          // typing, the same bytes can be a deliberate newer external revert
+          // (history restore / provider conflict choice) and must be allowed
+          // through even if mount-time normalization emitted them.
+          (value === lastEmittedRef.current ||
+            recentEmittedRef.current.includes(value) ||
+            recentEmittedRef.current.includes(normalizedValue))) ||
         (editorUnchangedSinceApply &&
           (value === lastAppliedValueRef.current ||
             normalizedValue === lastAppliedSerializedRef.current))
@@ -442,8 +448,6 @@ export function useCollabReconcile({
       // for non-idempotent input, fight every keystroke. Newer external content
       // retries so it still lands once they pause; older-or-equal content is a
       // stale poll and is dropped outright while focused.
-      const typingRecently =
-        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
       if (typingRecently) {
         if (externalNewer) {
           retry = setTimeout(() => apply(deferred), 700);
@@ -549,6 +553,13 @@ export function useCollabReconcile({
 
   const shouldIgnoreUpdate = (transaction: Transaction): boolean => {
     if (!editable || isSettingContentRef.current) return true;
+    // Collaboration can emit schema/default-paragraph transactions while the
+    // persisted Y.Doc is still loading and before the authoritative value has
+    // seeded/reconciled. Never let those transient pre-seed updates reach an
+    // app's local mirror or autosave path (Content serializes an empty paragraph
+    // as `<empty-block/>`, which is non-empty text and bypasses the generic
+    // registerEmitted empty-string guard).
+    if (collab && !seededRef.current) return true;
     if (transaction.getMeta(RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION)) {
       return true;
     }

package/corpus/core/src/collab/awareness-store.ts

@@ -149,23 +149,34 @@ export async function loadAwarenessRows(
   now: number = Date.now(),
 ): Promise<AwarenessEntry[]> {
   try {
-    await ensureTable();
-    const client = getDbExec();
-    const { rows } = await client.execute({
-      sql: `SELECT client_id, state, last_seen FROM _collab_awareness
-            WHERE doc_id = ? AND last_seen >= ?`,
-      args: [docId, now - ROW_TTL_MS],
-    });
-    return rows.map((row: any) => ({
-      clientId: Number(row.client_id),
-      state: String(row.state),
-      lastSeen: Number(row.last_seen),
-    }));
+    return await loadAwarenessRowsStrict(docId, now);
   } catch {
     return [];
   }
 }
 
+/**
+ * Strict awareness read for safety-critical callers that must distinguish
+ * "no active participants" from "presence storage could not be read."
+ */
+export async function loadAwarenessRowsStrict(
+  docId: string,
+  now: number = Date.now(),
+): Promise<AwarenessEntry[]> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT client_id, state, last_seen FROM _collab_awareness
+          WHERE doc_id = ? AND last_seen >= ?`,
+    args: [docId, now - ROW_TTL_MS],
+  });
+  return rows.map((row: any) => ({
+    clientId: Number(row.client_id),
+    state: String(row.state),
+    lastSeen: Number(row.last_seen),
+  }));
+}
+
 async function maybePurge(docId: string, now: number): Promise<void> {
   const last = _lastPurges.get(docId) ?? 0;
   if (now - last < PURGE_INTERVAL_MS) return;

package/corpus/core/src/collab/client.ts

@@ -579,7 +579,10 @@ class CollabDocConnection {
     this.awareness.setLocalStateField("visible", !isDocumentHidden());
   }
 
-  private handleAwarenessChange = (): void => {
+  private handleAwarenessChange = (
+    _changes?: { added: number[]; updated: number[]; removed: number[] },
+    origin?: unknown,
+  ): void => {
     const users: CollabUser[] = [];
     let hasAgent = false;
     this.awareness.getStates().forEach((state, clientId) => {
@@ -616,12 +619,20 @@ class CollabDocConnection {
       this.setSnapshot({ activeUsers, agentPresent: hasAgent });
     }
 
-    // Fast awareness push: whenever awareness changes (e.g. cursor moves,
-    // setPresence() calls), schedule a throttled POST so peers receive updates
-    // at ~150ms instead of waiting for the next poll cycle. Only active once a
+    // Fast awareness push: whenever OUR OWN awareness state changes (e.g.
+    // cursor moves, setPresence() calls), schedule a throttled POST so peers
+    // receive updates at ~150ms instead of waiting for the next poll cycle.
+    // Gated on origin === "local": this listener also fires for remote
+    // awareness changes (poll/SSE call `awareness.emit("change", [changes,
+    // "remote"])` after reconciling incoming states — see
+    // applyAwarenessEvent/poll above). Without the origin check, every
+    // peer's cursor move would also re-trigger THIS client to re-broadcast
+    // its own unchanged state, turning one person moving their mouse into
+    // O(n) redundant POSTs from every other connected client (an awareness
+    // storm that gets worse as more people join the doc). Only active once a
     // local user identity has been published (matches the previous per-hook
     // gating on `user`). The poll cycle remains the authoritative baseline.
-    if (this.lastSetUser && !this.disposed) {
+    if (this.lastSetUser && origin === "local" && !this.disposed) {
       scheduleAwarenessPush(
         this.baseUrl,
         this.docId,

package/corpus/core/src/collab/index.ts

@@ -126,6 +126,10 @@ export {
   type AwarenessEntry,
   type AwarenessChangeEvent,
 } from "./awareness.js";
+export {
+  loadAwarenessRows,
+  loadAwarenessRowsStrict,
+} from "./awareness-store.js";
 
 // Presence kit
 export {

package/corpus/core/src/collab/recent-edits.ts

@@ -21,6 +21,7 @@ import {
   RECENT_EDIT_TTL_MS,
   type AttributedRecentEdit,
   type RecentEdit,
+  type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 import { useEffect, useRef, useState } from "react";
 
@@ -34,16 +35,78 @@ export {
   type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 
+/**
+ * Hard cap on any single string carried in a recentEdits entry (quote,
+ * selector, path segment, label). Callers are expected to pass short
+ * excerpts already (existing call sites trim to 80–120 chars for a "what
+ * changed" snippet), but this is the ring's own size ceiling — a caller that
+ * forgets to trim (e.g. passing a whole paragraph/document as `quote`) must
+ * not blow up the awareness payload every connected client receives on the
+ * fast-push path, nor the `_collab_awareness` SQL row it gets mirrored into.
+ */
+const RECENT_EDIT_STRING_MAX = 500;
+
+function truncateString(value: string): string {
+  return value.length > RECENT_EDIT_STRING_MAX
+    ? value.slice(0, RECENT_EDIT_STRING_MAX)
+    : value;
+}
+
+function truncateDescriptor(
+  descriptor: RecentEditDescriptor,
+): RecentEditDescriptor {
+  // The union's last member (`{ kind: string; [key: string]: unknown }`) is an
+  // open-ended catch-all whose `kind` is a plain `string`, so a `switch` on
+  // `descriptor.kind` can't discriminate it away from the literal-kind
+  // members for the compiler — every property still type-checks as
+  // `unknown`. Read/write through an untyped view instead and lean on
+  // runtime checks; the return value is cast back to the real type below.
+  const d = descriptor as Record<string, unknown> & { kind: string };
+  if (d.kind === "text" && typeof d.quote === "string") {
+    return { ...d, quote: truncateString(d.quote) } as RecentEditDescriptor;
+  }
+  if (d.kind === "selector" && typeof d.selector === "string") {
+    return {
+      ...d,
+      selector: truncateString(d.selector),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "paths" && Array.isArray(d.paths)) {
+    return {
+      ...d,
+      paths: d.paths.map((p) =>
+        typeof p === "string" ? truncateString(p) : p,
+      ),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "doc") {
+    return descriptor;
+  }
+  // Open-ended shape — trim any string-valued fields defensively without
+  // knowing their names.
+  const trimmed: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(d)) {
+    trimmed[key] = typeof value === "string" ? truncateString(value) : value;
+  }
+  return trimmed as RecentEditDescriptor;
+}
+
 /**
  * Append an edit to a recentEdits ring, keeping the newest
- * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array. Descriptor
+ * strings and the label are truncated to {@link RECENT_EDIT_STRING_MAX}
+ * characters as a defensive cap on the awareness payload size.
  */
 export function appendRecentEdit(
   existing: RecentEdit[] | undefined,
   edit: RecentEdit,
 ): RecentEdit[] {
   const ring = Array.isArray(existing) ? existing.slice() : [];
-  ring.push(edit);
+  ring.push({
+    ...edit,
+    descriptor: truncateDescriptor(edit.descriptor),
+    label: edit.label ? truncateString(edit.label) : edit.label,
+  });
   if (ring.length > RECENT_EDITS_MAX) {
     ring.splice(0, ring.length - RECENT_EDITS_MAX);
   }

package/corpus/core/src/index.browser.ts

@@ -10,6 +10,7 @@ export {
   refreshAgentChatContext,
   removeAgentChatContextItem,
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
   setAgentChatContextItem,
   setContextToAgentChat,
   isEmbedMcpChatBridgeActive,

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -8561,10 +8561,34 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
       // covers the initial dispatch (a connected client is polling the claim),
       // but a server-chained CONTINUATION handoff has no foreground watching
       // it: if the dispatch is lost after the successor row was inserted, the
-      // row would sit at dispatch_mode='background' forever and the turn hangs
-      // silently. This sweep reaps such rows into a loud, attributable error
-      // (`background_worker_never_started`) that the client renders, instead
-      // of an idle spinner. Cheap: one indexed-ish query per 2-min window.
+      // row would otherwise sit at dispatch_mode='background' forever and the
+      // turn hangs silently. `chainServerDrivenContinuation` (production-agent.ts)
+      // leaves exactly such a row behind — status='running', dispatch_mode=
+      // 'background', `dispatch_payload` intact — when it exhausts its own
+      // dispatch retry budget, instead of erroring it immediately. This sweep
+      // gives that row a real chance to RECOVER: within
+      // `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` of its original
+      // `started_at` it redispatches the handoff (same `_process-run`
+      // processor, same persisted payload); past that bound it falls back to
+      // the existing loud reap (`background_worker_never_started`) so a
+      // genuinely dead handoff still fails loud, never silently. A
+      // redispatch is always safe to attempt — even a duplicate or
+      // late-arriving one — because the worker's `claimBackgroundRun` atomic
+      // CAS (status='running' AND dispatch_mode='background' -> 'background-
+      // processing') is the sole gate on actual execution; a row that was
+      // already claimed or already reaped by a concurrent path just loses the
+      // CAS and no-ops. Cheap: one indexed-ish query per 2-min window.
+      //
+      // THREE-SITE INVARIANT (keep in lockstep): this sweep only ever sees the
+      // deferred successor because the ~1s client poll in
+      // `getActiveRunForThreadAsync` (run-manager.ts) skips its own
+      // `reapUnclaimedBackgroundRun` while the row is within the redispatch
+      // bound (`shouldRedispatchUnclaimedBackgroundRun`). If a future change
+      // makes that client poll reap deferred successors at the 25s grace
+      // again, this sweep will almost never win the race for connected clients.
+      // Do not edit one site without the others (producer:
+      // chainServerDrivenContinuation in production-agent.ts; guard:
+      // run-manager.ts; recovery actor: here).
       (() => {
         let lastSweep = 0;
         const SWEEP_INTERVAL_MS = 2 * 60 * 1000;
@@ -8577,22 +8601,85 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
 
             (async () => {
               const {
-                listUnclaimedBackgroundRunIds,
+                listUnclaimedBackgroundRunRows,
                 reapUnclaimedBackgroundRun,
+                updateRunHeartbeat,
+                shouldRedispatchUnclaimedBackgroundRun,
               } = await import("../agent/run-store.js");
-              let runIds: string[];
+              const { resolveAgentChatProcessRunDispatchPath } =
+                await import("../agent/durable-background.js");
+              const { fireInternalDispatch } =
+                await import("./self-dispatch.js");
+              let rows: { id: string; startedAt: number }[];
               try {
-                runIds = await listUnclaimedBackgroundRunIds();
+                rows = await listUnclaimedBackgroundRunRows();
               } catch {
                 return; // Table may not exist yet on first boot
               }
-              for (const staleRunId of runIds) {
+              for (const row of rows) {
                 try {
-                  const reaped = await reapUnclaimedBackgroundRun(staleRunId);
+                  if (shouldRedispatchUnclaimedBackgroundRun(row)) {
+                    // Bump liveness BEFORE attempting the redispatch so the
+                    // row doesn't look freshly-stale again the instant this
+                    // tick returns — best-effort, the CAS is what actually
+                    // matters for correctness, not this timing.
+                    await updateRunHeartbeat(row.id).catch(() => {});
+                    try {
+                      // DELIBERATE: this marker omits `continuationCount`.
+                      // `chainServerDrivenContinuation` (production-agent.ts)
+                      // reads `backgroundRunMarker.continuationCount` to
+                      // compute `backgroundContinuationCount`, defaulting to 0
+                      // when absent — so a chunk recovered here always starts
+                      // a fresh nested-dispatch segment at depth 0, regardless
+                      // of how deep the chain was before this sweep picked it
+                      // up. This is what makes the sweep a genuine CHAIN
+                      // BREAK, not just a retry: this redispatch fires from an
+                      // unrelated, timer-driven invocation rather than from
+                      // inside the prior chain's own live execution, so
+                      // starting its nested-depth count over at 0 here is
+                      // correct — see `MAX_NESTED_SELF_DISPATCH_DEPTH` in
+                      // production-agent.ts for why nested depth is bounded
+                      // and how this reset keeps a long turn progressing past
+                      // Netlify's undocumented self-invocation loop-protection
+                      // limit instead of dying at it. Do not "fix" this by
+                      // adding `continuationCount` back without re-reading
+                      // that constant's doc comment.
+                      await fireInternalDispatch({
+                        path: resolveAgentChatProcessRunDispatchPath(),
+                        taskId: row.id,
+                        body: {
+                          internalContinuation: true,
+                          [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                            runId: row.id,
+                            payloadRef: true,
+                          },
+                        },
+                        awaitResponse: true,
+                        responseTimeoutMs: 15_000,
+                      });
+                      console.error(
+                        "[agent-chat] redispatched unclaimed background run (handoff recovery):",
+                        row.id,
+                      );
+                    } catch (redispatchErr) {
+                      console.error(
+                        "[agent-chat] unclaimed background run redispatch attempt failed (retrying until the redispatch bound, then reaping):",
+                        row.id,
+                        redispatchErr instanceof Error
+                          ? redispatchErr.message
+                          : redispatchErr,
+                      );
+                    }
+                    continue;
+                  }
+                  // Redispatch bound exceeded — this handoff is not
+                  // recovering. Fall back to the pre-existing loud reap so
+                  // the turn fails loud instead of retrying forever.
+                  const reaped = await reapUnclaimedBackgroundRun(row.id);
                   if (reaped) {
                     console.error(
-                      "[agent-chat] swept unclaimed background run (handoff lost):",
-                      staleRunId,
+                      "[agent-chat] swept unclaimed background run (handoff lost, redispatch bound exceeded):",
+                      row.id,
                     );
                   }
                 } catch {

package/corpus/core/src/server/builder-design-systems.ts

@@ -16,6 +16,21 @@ export interface BuilderDesignSystemCodeFileInput {
   filename: string;
   content: string;
   mimeType?: string;
+  /**
+   * How `content` is encoded. Defaults to `"utf8"` (existing behavior,
+   * unchanged for every current text-file caller). Pass `"base64"` for
+   * binary files -- most importantly `.fig` (a zip/kiwi binary container,
+   * never valid UTF-8 text). Without this, a `.fig` upload silently
+   * corrupts: `mimeTypeForBuilderDesignSystemFilename` already special-cases
+   * `.fig` as `application/octet-stream`, but the actual byte pipeline ran
+   * every file through `TextEncoder().encode()` regardless, which mangles
+   * any byte >= 0x80 in a binary-as-string payload (or, if the caller
+   * base64-encoded first with no decode step here, stores the literal
+   * base64 text instead of the decoded binary). Callers sending `.fig`/PDF/
+   * other binary bytes must base64-encode `content` and set this to
+   * `"base64"`.
+   */
+  encoding?: "utf8" | "base64";
 }
 
 export interface BuildBuilderDesignSystemIndexFilesOptions {
@@ -184,9 +199,20 @@ export function buildBuilderDesignSystemIndexFiles({
   const files: BuilderDesignSystemIndexFile[] = [];
   let totalBytes = 0;
 
-  function pushTextFile(filename: string, content: string, mimeType?: string) {
+  function pushFile(
+    filename: string,
+    content: string,
+    mimeType?: string,
+    encoding?: "utf8" | "base64",
+  ) {
     const normalizedName = filename.replace(/^\/+/, "") || "code.txt";
-    const data = encoder.encode(content);
+    // `.fig`/PDF/other binary payloads must round-trip through base64, not
+    // UTF-8 -- TextEncoder().encode() on a binary-as-string payload mangles
+    // any byte >= 0x80. See BuilderDesignSystemCodeFileInput.encoding.
+    const data =
+      encoding === "base64"
+        ? new Uint8Array(Buffer.from(content, "base64"))
+        : encoder.encode(content);
     if (data.byteLength === 0) return;
     if (totalBytes + data.byteLength > maxTotalCodeBytes) return;
     totalBytes += data.byteLength;
@@ -201,7 +227,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   if (designMd?.trim()) {
-    pushTextFile(
+    pushFile(
       designMdFilename?.trim() || "design.md",
       designMd,
       "text/markdown",
@@ -209,7 +235,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   for (const file of (codeFiles ?? []).slice(0, maxCodeFiles)) {
-    pushTextFile(file.filename, file.content, file.mimeType);
+    pushFile(file.filename, file.content, file.mimeType, file.encoding);
   }
 
   return files;

package/corpus/templates/clips/.agents/skills/ai-video-tools/SKILL.md

@@ -126,7 +126,7 @@ Transcription takes an audio file and returns text + segments. That's not a prom
 **Provider priority:**
 
 1. **Native (highest priority).** The browser's Web Speech API, desktop local Whisper/macOS SFSpeech when available, and desktop Web Speech fallback on non-mac run during recording and save results via `save-browser-transcript`. This gives an instant transcript with no API key when the local/browser recognizer is available. When `request-transcript` runs afterward, it preserves the ready native transcript and only falls back to a cloud provider if native text is missing.
-2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments.
+2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments. Retry a failed transcript with `force: true`; pass `regenerate: true` to replace an existing ready transcript from the stored recording media. Regeneration keeps the prior ready transcript available if the new provider attempt fails.
 3. **Cloud fallback — Groq Whisper.** `GROQ_API_KEY` → `https://api.groq.com/openai/v1/audio/transcriptions`, model `whisper-large-v3-turbo`. Fast (~$0.04/hour of audio) Whisper-compatible speech-to-text used when Builder is unavailable.
 
 Clips never routes recording/meeting audio to OpenAI for transcription. (Groq's endpoint is OpenAI-_compatible_ in request shape only — the audio goes to Groq, not OpenAI.)

package/corpus/templates/clips/.agents/skills/video-sharing/SKILL.md

@@ -14,6 +14,12 @@ description: >-
 
 Recording sharing uses the framework `sharing` system — not a custom share table. Recordings are registered via `registerShareableResource({ type: "recording", ... })` in `server/db/index.ts`. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted and handle per-user grants, per-org grants, and the three visibility levels (`private` / `org` / `public`).
 
+Unlike the framework-wide private default, normal Clips recordings and uploaded
+videos default to **public** so their copied share links work immediately.
+Embedded bug-report recordings are the exception and default to organization
+visibility. Callers can still explicitly create a private or organization-only
+recording, and owners/admins can change visibility from the Share dialog.
+
 Clips **adds two things** on top of the framework system:
 
 1. **Password** — an optional bcrypt'd string on the `recordings` row. When set, all non-owner viewers must enter it to play the recording.
@@ -62,7 +68,7 @@ import { ShareDialog } from "@agent-native/core/client";
     </>
   }
   embedTabContent={<EmbedSnippetAndOptions recordingId={recording.id} />}
-/>
+/>;
 ```
 
 - `shareUrl` / `embedUrl` — the copy-link and embed URLs the framework renders in its tabs.
@@ -163,11 +169,11 @@ Required Slack app setup:
 Recordings can expose URLs meant for external agents without handing over raw
 video bytes:
 
-| Endpoint | Meaning |
-| -------- | ------- |
-| `/api/agent-context.json?id=<recordingId>` | Clip metadata, transcript summary, recommended frames, and API discovery links |
-| `/api/agent-transcript.json?id=<recordingId>` | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
-| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp |
+| Endpoint                                          | Meaning                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript summary, recommended frames, and API discovery links                               |
+| `/api/agent-transcript.json?id=<recordingId>`     | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
+| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp                                |
 
 These endpoints follow the same access model as `/api/public-recording`, plus a
 temporary agent-link path:

package/corpus/templates/clips/AGENTS.md

@@ -34,6 +34,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.
+- Use `request-transcript --recordingId=<id> --force=true` to retry a failed
+  transcript. Pass `--regenerate=true` to replace an existing ready transcript
+  from the stored recording media; if regeneration fails, keep the prior ready
+  transcript available.
 - 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

package/corpus/templates/clips/actions/create-recording.ts

@@ -24,6 +24,7 @@ import {
 } from "../server/lib/recordings.js";
 import { setResumableSession } from "../server/lib/resumable-session.js";
 import { shouldEnableStreamingUpload } from "../server/lib/streaming-upload-mode.js";
+import { allowsSqlRecordingChunkScratch } from "../server/lib/video-storage.js";
 import { createRecordingSchema } from "./lib/create-recording-schema.js";
 import { DEFAULT_RECORDING_TITLE } from "./lib/title-source.js";
 
@@ -92,6 +93,7 @@ export default defineAction({
       shouldEnableStreamingUpload({
         client: args.streamingUploadClient,
         mimeType: args.mimeType,
+        bufferedFallbackAvailable: allowsSqlRecordingChunkScratch(),
       }) &&
       uploadProvider?.resumable
     ) {

package/corpus/templates/clips/actions/lib/create-recording-schema.ts

@@ -62,8 +62,10 @@ export const createRecordingSchema = z.object({
     .describe("Height of the recording in pixels (may be 0 until finalized)"),
   visibility: z
     .enum(["private", "org", "public"])
-    .optional()
-    .describe("Initial share visibility for the recording"),
+    .default("public")
+    .describe(
+      "Initial share visibility for the recording (defaults to public)",
+    ),
   mimeType: z
     .string()
     .optional()
@@ -74,7 +76,7 @@ export const createRecordingSchema = z.object({
     .boolean()
     .optional()
     .describe(
-      "Request the resumable streaming upload path. Deployments must also set CLIPS_ENABLE_STREAMING_UPLOAD; otherwise recordings use the buffered fallback.",
+      "Request the resumable streaming upload path. Hosted deployments use it automatically because SQL chunk buffering is unavailable; local deployments can opt in with CLIPS_ENABLE_STREAMING_UPLOAD.",
     ),
   streamingUploadClient: z
     .enum(["desktop-native"])