@agent-native/core 0.145.5 → 0.145.7

package/corpus/templates/clips/.agents/skills/turn-into-app/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: turn-into-app
 description: >-
-  Turn a proven thread, skill, or workflow into a runnable Agent-Native app
-  with simple buttons, visible agent steps, preview, and deployment handoff.
-  Use when a user invokes `/turn-into-app` or asks to make a workflow into an
-  app.
+  Turn visible project context, a proven thread, skill, or workflow into a
+  runnable Agent-Native app with simple buttons, visible agent steps, preview,
+  and deployment handoff. Use when a user invokes `/turn-into-app` or asks to
+  make a workflow into an app.
 user-invocable: true
 scope: both
 metadata:
@@ -17,34 +17,72 @@ metadata:
 
 This is an end-to-end build skill, not a request for an app proposal.
 
-- With no argument, use the current thread as the source. This is the normal
-  invocation at the end of a successful workflow.
+- With no argument, choose the source in this order: visible project context,
+  then the current thread. A fresh Claude or ChatGPT Project is a valid source
+  on its first turn. Treat its visible project instructions, knowledge files,
+  and supplied past runs as the source; a completed thread is not required.
+  Treat the current turn as a request or configuration unless it contains a
+  concrete repeatable workflow.
 - With a named skill or local workflow, read that source and package it
   immediately, even at the beginning of a thread. For example,
   `/turn-into-app /some-skill` means “turn `/some-skill` into an app.”
 - With an attachment or path, read the supplied artifact as the source.
 - Do not ask the user to restate context that is already in the thread.
-- When invoked from an Agent-Native app, keep the current thread as the source
-  and use the available workspace/coding-agent handoff when the current runtime
-  cannot edit files. Do not claim the app exists without an actual path and
-  verification result.
+- When invoked from an Agent-Native app, use its visible project context first,
+  then the current thread, and use the available workspace/coding-agent
+  handoff when the current runtime cannot edit files. Do not claim the app
+  exists without an actual path and verification result.
 
 ## Source support
 
-Supported source paths today are the current Codex thread, a named skill, or a
-local workflow/transcript supplied as a path or attachment. An exported
-ChatGPT or Claude transcript can use the same local-file path today.
+Supported source paths today are visible Claude or ChatGPT Project context, the
+current Codex or host thread, a named skill, or a local workflow/transcript
+supplied as a path or attachment. An exported ChatGPT or Claude transcript can
+use the same local-file path today.
 
-ChatGPT shared-conversation import and Claude web conversation/project import
-are **coming soon**. Do not claim private web access, invent an importer, add
-fake OAuth, or scrape a logged-in page without an explicit supported adapter.
-If a user gives one of those URLs before an adapter exists, ask for an export or
-transcript instead and treat it as imported source material.
+Claude and ChatGPT Project context is supported only when the host supplies it
+to the model in the current context. The MCP connector does not read hidden
+project chats, private URLs, account settings, or credentials. Do not claim
+private web access, invent an importer, add fake OAuth, or scrape a logged-in
+page. If the needed context is not visible, ask for an export, transcript, or
+attachment and treat that artifact as imported source material.
 
 Deliver a fresh app in a new directory, implement the repeatable workflow with
 buttons and agent handoffs, start its dev server, verify the main path, and
 continue through build/deployment handoff. Do not stop at a plan.
 
+## Fresh project context mode
+
+When the source is a fresh Claude or ChatGPT Project, build a short source brief
+before creating the app. Read the host-provided context in this order:
+
+1. Project instructions and configuration: goal, audience, constraints, output
+   standards, approved tools, and integration expectations. Treat these as
+   product configuration, not as a transcript.
+2. Knowledge files and attachments: read the relevant files fully, preserve
+   their provenance, and reduce them to bounded references, IDs, URLs, or
+   summaries for the new app. Do not copy secrets or large raw payloads into
+   prompts or SQL.
+3. Past runs or examples that are actually visible in the context: select at
+   most 1-3 successful, representative runs. Extract repeatable decisions and
+   review criteria. Treat one-off answers and private data as examples, not as
+   product behavior. If no runs are supplied, proceed from the instructions
+   and knowledge files and say that examples were not available.
+4. The current turn: use it for the requested app boundary, target workspace,
+   naming, and any explicit corrections.
+
+Record the brief with these headings before handoff: source and provenance,
+project goal, configuration and constraints, knowledge sources, repeatable
+workflow, inputs and outputs, judgment and review points, representative runs,
+integrations and permissions, and unknowns. This is the compact contract for
+the app. It keeps the new app useful without pretending that hidden Project
+history was imported. See [the fresh Project reference](references/fresh-project.md)
+for the host setup and brief template.
+
+If the visible Project context has no concrete repeatable job, ask for one
+focused clarification or a representative artifact. Do not fall back to a
+generic “what app do you want to make?” builder.
+
 ## Source selection guard
 
 The generated app must implement the concrete workflow found in the source. It
@@ -151,6 +189,14 @@ pnpm exec agent-native add-app <slug> --template=chat
 Do not use `create` for an existing workspace; it scaffolds a new standalone
 workspace rather than adding an app to the current one.
 
+When the source came from a fresh external Project and the target is a Builder
+workspace, prefer the available Dispatch MCP workspace handoff after writing
+the source brief. Call `start-workspace-app-creation` with a concise prompt,
+the inferred app id, and the brief's repeatable workflow. Pass selected
+workspace resource IDs when they are available, rather than pasting entire
+knowledge files. Continue from the returned workspace path or Builder handoff
+and report the actual verification result.
+
 Use a first-party template only when it materially fits the workflow. Keep the
 new app independent from the source thread's working tree unless the user
 explicitly asks to extend an existing app.
@@ -167,13 +213,20 @@ should make the repeated path obvious without hiding the agent's judgment:
 - Give each important repeated moment a clear button, such as “Analyze,”
   “Suggest options,” “Draft,” “Review,” or “Publish.” Use the source's actual
   vocabulary when it is clear.
-- Put deterministic reads, writes, approvals, and publishing in `actions/`
-  with `defineAction`. The UI and agent must call the same action surface.
+- Put deterministic reads, writes, approvals, provider fetches, and publishing
+  in focused `actions/` with `defineAction`. The UI and agent must call the
+  same action surface.
+- If a workflow is framed as research, analysis, generation, recommendation,
+  or synthesis, start it in the AgentSidebar and let the agent orchestrate
+  those actions. Do not hide an AI-shaped multi-step workflow behind one
+  opaque action just because the implementation is deterministic.
 - Use application state for the current screen, selected item, and focused
   object so the agent can see where the user is.
-- Use `sendToAgentChat({ message, context, submit: true })` for intentional
-  button-triggered agent work. Use `submit: false` when the user should review
-  or edit the proposed prompt first.
+- Use `sendToAgentChat({ message, context, submit: true, openSidebar: true })`
+  for intentional button-triggered agent work. Use `submit: false` when the
+  user should review or edit the proposed prompt in the AgentSidebar first.
+  Keep follow-up and revision prompts in that same thread; do not add a second
+  freeform textbox beside the result.
 - Pass IDs, URLs, and bounded summaries in context. Do not paste large provider
   dumps into prompts, call an LLM directly from the browser, or invent fake
   progress.

package/corpus/templates/clips/.agents/skills/turn-into-app/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Turn Into App"
-  short_description: "Turn a thread or skill into a runnable app"
-  default_prompt: "Scan the current thread, turn the workflow into a new Agent-Native app with clear buttons, run it locally, verify it, and complete the deployment handoff."
+  short_description: "Turn project context or a workflow into a runnable app"
+  default_prompt: "Use the visible project context first, then any supplied workflow. Turn the instructions, knowledge files, and selected successful runs into a new Agent-Native app with clear buttons, run it locally, verify it, and complete the deployment handoff."

package/corpus/templates/clips/.agents/skills/turn-into-app/references/fresh-project.md

@@ -0,0 +1,64 @@
+# Fresh Project source guide
+
+Use this guide when `/turn-into-app` is invoked in a new Claude or ChatGPT
+Project rather than after a completed thread.
+
+## What the host can provide
+
+The source is whatever the host put in the model's current context:
+
+- Project instructions: the job, audience, constraints, quality bar, and
+  approved tools or integrations.
+- Knowledge files and attachments: reference material, templates, examples,
+  and links that the app should use.
+- Past runs: only conversations or outputs the host actually supplied. They
+  are examples and evaluation material, not an automatic import of every
+  private Project conversation.
+- The current request: the app boundary, target workspace, name, and explicit
+  corrections.
+
+Do not infer hidden system prompts, account settings, private history, API keys,
+or credentials. The Dispatch MCP connector can start a workspace app creation,
+but it cannot unlock or scrape private Project content.
+
+## Source brief
+
+Write a compact brief before starting the app:
+
+```text
+Source: host-provided Claude/ChatGPT Project context
+Provenance: project instructions, selected knowledge files, and visible runs
+Project goal:
+Configuration and constraints:
+Knowledge sources:
+Repeatable workflow:
+Inputs and outputs:
+Judgment and review points:
+Representative runs: none, or 1-3 selected examples
+Integrations and permissions:
+Unknowns and follow-up:
+```
+
+Keep source references bounded. Prefer a file name, URL, resource ID, or short
+summary over a large pasted document. Do not put secrets or raw customer data
+in the brief.
+
+## Fresh-box setup
+
+Install the exported `turn-into-app` skill in the host when the host supports
+skills. For a ChatGPT Project or any host that exposes only the MCP connector,
+also place the skill instructions or this reference in the Project
+instructions/knowledge files. Then add and authenticate the Dispatch MCP
+connector from the packaged `adapters/chatgpt-mcp/connector.json`.
+
+In a new Project chat, say:
+
+```text
+Turn this project into an app. Use the visible Project instructions,
+knowledge files, and any selected successful runs as the source. Create the
+app in the connected Agent-Native workspace, keep the source brief bounded,
+and report the real path and verification result.
+```
+
+If the host does not show the Project instructions or files to the model, stop
+and request an export or attachment. Do not claim that the Project was read.

package/corpus/templates/clips/actions/lib/audio-only-transcription.ts

@@ -15,6 +15,10 @@ const requireFromThisFile = createRequire(import.meta.url);
 let cachedFfmpegStaticPath: string | null | undefined;
 
 export type AudioOnlyExtractionErrorCode =
+  // The stored recording has no audio stream at all — a measurement of the
+  // file, distinct from "we looked and found no speech". Kept separate so the
+  // message can say so instead of blaming the recording.
+  | "NO_AUDIO_SAVED"
   | "NO_AUDIO_TRACK"
   | "NO_SPEECH_DETECTED"
   | "FFMPEG_UNAVAILABLE"

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

@@ -54,6 +54,11 @@ import {
 } from "../server/lib/recordings.js";
 import { isBuilderCreditsExhaustedMessage } from "../shared/builder-credits.js";
 import { normalizeLoomShareUrl } from "../shared/loom.js";
+import {
+  isRetryableTranscriptFailure,
+  transcriptFailureMessage,
+  type TranscriptFailureCode,
+} from "../shared/transcript-failure.js";
 import {
   buildCaptionSegmentsFromText,
   normalizeTranscriptSegments,
@@ -221,6 +226,13 @@ export function recordingMediaFetchTimeoutMs(
 const MAX_AUTO_TRANSCRIPT_RETRIES = 2;
 const AUTO_TRANSCRIPT_RETRY_BACKOFF_MS = [5_000, 20_000];
 
+/** The typed code an error already carries, if any. */
+function transcriptFailureCodeFor(err: unknown): TranscriptFailureCode | null {
+  return err instanceof AudioOnlyExtractionError
+    ? (err.code as TranscriptFailureCode)
+    : null;
+}
+
 function isTransientTranscriptionError(err: unknown): boolean {
   if (isTransientExtractionError(err)) return true;
   if (err instanceof Error) {
@@ -641,7 +653,13 @@ async function failAudioOnlyPreparation({
   });
   if (preserved) return preserved;
 
-  const transient = isTransientTranscriptionError(err);
+  // The code decides retryability. `isTransientTranscriptionError` stays as the
+  // fallback for errors that carry no code yet — it reads regexes over prose,
+  // which is why a reworded message could once change whether a clip retried.
+  const failureCode = transcriptFailureCodeFor(err);
+  const transient = failureCode
+    ? isRetryableTranscriptFailure(failureCode)
+    : isTransientTranscriptionError(err);
   const nextRetryCount = currentRetryCount + 1;
 
   await upsertTranscriptRow(db, {
@@ -649,6 +667,7 @@ async function failAudioOnlyPreparation({
     ownerEmail,
     status: "failed",
     failureReason: reason,
+    failureCode: failureCode ?? "UNKNOWN",
     segmentsJson: "[]",
     fullText: "",
     now,
@@ -1136,9 +1155,12 @@ const requestTranscriptAction = defineAction({
       const videoUrl = rec.videoUrl;
       if (!videoUrl) throw new Error("Recording has no videoUrl");
       if (rec.hasAudio === false) {
+        // NOT "no speech was detected" — this is a measurement of the stored
+        // file, and blaming the recording sent people hunting for a microphone
+        // problem when the screen-share simply never included audio.
         throw new AudioOnlyExtractionError(
-          "NO_AUDIO_TRACK",
-          "No speech was detected because this recording was saved without audio.",
+          "NO_AUDIO_SAVED",
+          transcriptFailureMessage("NO_AUDIO_SAVED"),
         );
       }
       audioMediaPromise ??= (async () => {
@@ -1464,14 +1486,33 @@ const requestTranscriptAction = defineAction({
     const reason = builderError
       ? "No native transcript was captured, and Builder transcription could not finish. Retry transcription or check Builder connection and recording audio."
       : "No transcript was captured by native speech recognition, and Builder transcription is not configured.";
+    // A cloud failure gets the SAME transient-retry treatment the audio-only
+    // path already has (see `failAudioOnlyPreparation`). This branch classified
+    // the error, logged it, and then fell through with no retry scheduled and
+    // no `retryCount` written — so the one path users report as "it works if I
+    // retry" was the one path that never retried itself. Production bears that
+    // out: `retry_count` averages 0.0 on these rows, while 12 of them say
+    // `fetch failed` and 11 say `timed out after 45` — textbook transient.
+    const cloudTransient = builderError
+      ? isTransientTranscriptionError(new Error(builderError))
+      : false;
+    const cloudNextRetryCount = currentRetryCount + 1;
     await upsertTranscriptRow(db, {
       recordingId: args.recordingId,
       ownerEmail,
       status: "failed",
       failureReason: reason,
+      failureCode: builderError ? "CLOUD_FAILED" : "CLOUD_UNCONFIGURED",
       now,
+      ...(cloudTransient ? { retryCount: cloudNextRetryCount } : {}),
     });
     await writeAppState("refresh-signal", { ts: Date.now() });
+    if (cloudTransient) {
+      scheduleAutoTranscriptRetry({
+        recordingId: args.recordingId,
+        nextRetryCount: cloudNextRetryCount,
+      });
+    }
     console.warn(`[clips] ${reason}`);
     return {
       recordingId: args.recordingId,
@@ -1488,6 +1529,11 @@ async function upsertTranscriptRow(
     ownerEmail: string;
     status: "pending" | "ready" | "failed";
     failureReason: string | null;
+    /**
+     * Machine-readable cause. This is what decides retryability; the prose in
+     * `failureReason` is rendered from it and is for humans only.
+     */
+    failureCode?: TranscriptFailureCode | null;
     language?: string;
     segmentsJson?: string;
     fullText?: string;
@@ -1523,6 +1569,8 @@ async function upsertTranscriptRow(
         ownerEmail: row.ownerEmail,
         status: row.status,
         failureReason: row.failureReason,
+        // Cleared on success so a recovered row does not keep a stale cause.
+        failureCode: row.status === "failed" ? (row.failureCode ?? null) : null,
         ...(row.language ? { language: row.language } : {}),
         ...(row.segmentsJson ? { segmentsJson: row.segmentsJson } : {}),
         ...(row.fullText !== undefined ? { fullText: row.fullText } : {}),
@@ -1539,6 +1587,7 @@ async function upsertTranscriptRow(
       fullText: row.fullText ?? "",
       status: row.status,
       failureReason: row.failureReason,
+      failureCode: row.status === "failed" ? (row.failureCode ?? null) : null,
       retryCount: retryCount ?? 0,
       createdAt: row.now,
       updatedAt,

package/corpus/templates/clips/app/components/recorder/recorder-engine.ts

@@ -10,6 +10,7 @@ import {
 } from "@shared/media-device-selection";
 import {
   SCREEN_CAPTURE_FRAME_RATE,
+  screenCaptureDisplayOptions,
   screenCaptureVideoConstraints,
 } from "@shared/recording-capture";
 import {
@@ -888,16 +889,8 @@ export class RecorderEngine {
       const displaySurface = normalizeDisplaySurfaceForRuntime(
         this.opts.displaySurface ?? "window",
       );
-      const displayOptions: ExtendedDisplayMediaOptions = {
-        video: screenCaptureVideoConstraints(displaySurface),
-        audio: wantsMic,
-        // Let "Browser tab" open the tab picker. preferCurrentTab turns it
-        // into a current-tab shortcut, which makes choosing another tab harder.
-        selfBrowserSurface:
-          displaySurface === "browser" ? "include" : "exclude",
-        surfaceSwitching: "include",
-        systemAudio: wantsMic ? "include" : "exclude",
-      };
+      const displayOptions: ExtendedDisplayMediaOptions =
+        screenCaptureDisplayOptions(displaySurface);
 
       if (wantsMic || wantsDisplay) {
         this.audioMixCtx?.close().catch(() => {});

package/corpus/templates/clips/app/routes/r.$recordingId.tsx

@@ -1473,6 +1473,7 @@ export default function RecordingPage() {
                     >
                       <span>{t(item.labelKey)}</span>
                       {item.tooltipKey ? (
+                        // guard:allow-large-help-icon - menu item tooltip icon
                         <IconHelpCircle
                           aria-hidden="true"
                           className="h-3.5 w-3.5 shrink-0 text-muted-foreground/70"

package/corpus/templates/clips/changelog/2026-08-07-screen-recordings-now-capture-tab-and-system-audio-even-when.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-07
+---
+
+Screen recordings now capture tab and system audio even when the microphone is off, so transcripts are generated instead of failing with a misleading no-speech message.

package/corpus/templates/clips/changelog/2026-08-07-transcription-now-retries-transient-cloud-failures-automatic.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-07
+---
+
+Transcription now retries transient cloud failures automatically, and failure messages say what actually went wrong instead of blaming the recording.

package/corpus/templates/clips/server/db/schema.ts

@@ -246,6 +246,13 @@ export const recordingTranscripts = table("recording_transcripts", {
     .notNull()
     .default("pending"),
   failureReason: text("failure_reason"),
+  // The MACHINE-READABLE reason, and the one that decides retryability — see
+  // shared/transcript-failure.ts. `failureReason` above is prose rendered from
+  // this and is for humans only; production accumulated 39 distinct strings
+  // for what turned out to be a handful of conditions, and retryability was
+  // being re-derived by regex over that prose. Nullable for rows written
+  // before this column existed.
+  failureCode: text("failure_code"),
   // Count of automatic retries already attempted after a transient failure
   // (ffmpeg timeout, transient provider/network error). Bounds the
   // fire-and-forget auto-retry pass in request-transcript.ts so a repeatedly

package/corpus/templates/clips/server/plugins/db.ts

@@ -1146,6 +1146,14 @@ const migrations = runMigrations(
         expires_at INTEGER NOT NULL
       )`,
     },
+    {
+      version: 64,
+      name: "recording-transcripts-failure-code",
+      // Additive. Existing rows keep failure_code NULL and their prose; new
+      // failures record a code that owns retryability instead of having it
+      // re-derived by regex over the message.
+      sql: `ALTER TABLE recording_transcripts ADD COLUMN failure_code TEXT`,
+    },
   ],
   { table: "clips_migrations" },
 );

package/corpus/templates/clips/shared/recording-capture.ts

@@ -35,3 +35,41 @@ export function screenCaptureVideoConstraints(
     displaySurface,
   };
 }
+
+export type ScreenCaptureDisplayOptions = {
+  video: ScreenCaptureVideoConstraints;
+  audio: boolean;
+  selfBrowserSurface: "include" | "exclude";
+  surfaceSwitching: "include" | "exclude";
+  systemAudio: "include" | "exclude";
+};
+
+/**
+ * The `getDisplayMedia` options for a screen recording.
+ *
+ * Screen/tab audio is requested ALWAYS, and deliberately does not depend on
+ * whether the microphone is on. They are two different sources, and one toggle
+ * used to govern both: with the mic off, Chrome was never even offered the
+ * "share tab audio" checkbox, so a screen recording of a call or a demo
+ * captured zero audio tracks. Measured in production, 345 recordings landed
+ * with `has_audio = false` — 95 over a minute, 17 over five — and each was told
+ * "No speech was detected because this recording was saved without audio",
+ * blaming the recording for a capture setting. That was 64% of recent
+ * transcript failures. The Chrome extension always requested display audio and
+ * never had the problem.
+ *
+ * Declining the checkbox is still respected; the user simply gets the choice.
+ */
+export function screenCaptureDisplayOptions(
+  displaySurface: ScreenCaptureSurface,
+): ScreenCaptureDisplayOptions {
+  return {
+    video: screenCaptureVideoConstraints(displaySurface),
+    audio: true,
+    // Let "Browser tab" open the tab picker. preferCurrentTab turns it into a
+    // current-tab shortcut, which makes choosing another tab harder.
+    selfBrowserSurface: displaySurface === "browser" ? "include" : "exclude",
+    surfaceSwitching: "include",
+    systemAudio: "include",
+  };
+}

package/corpus/templates/clips/shared/transcript-failure.ts

@@ -0,0 +1,89 @@
+/**
+ * One vocabulary for why a transcript did not happen.
+ *
+ * Production accumulated **39 distinct `failure_reason` strings** across 1100
+ * failed rows, introduced on five separate dates across four files and three
+ * capture surfaces. No commit ever owned the terminal-failure vocabulary, so
+ * every fix added its own sentence. Two of those strings were the same
+ * condition renamed ("backup transcription" → "Builder transcription"), which
+ * silently forked every downstream count.
+ *
+ * Worse, a typed code already existed (`AudioOnlyExtractionErrorCode`), was
+ * thrown, and was discarded at the persistence boundary — after which
+ * retryability was re-derived by running regexes over the English prose. A
+ * message reworded for clarity could therefore change whether a transcript
+ * retried.
+ *
+ * So: the CODE is the record, prose is rendered from it, and retryability is a
+ * property of the code. Adding a failure mode means adding one entry here, not
+ * a new sentence at a call site.
+ */
+
+/** Why a transcript ended in `failed`. Persisted; do not renumber or reword. */
+export type TranscriptFailureCode =
+  // --- audio extraction (mirrors AudioOnlyExtractionErrorCode) ---
+  | "NO_AUDIO_TRACK"
+  | "NO_SPEECH_DETECTED"
+  | "FFMPEG_UNAVAILABLE"
+  | "EXTRACTION_FAILED"
+  | "TIMEOUT"
+  // --- transcript level ---
+  /** The recording itself was saved with no audio stream at all. */
+  | "NO_AUDIO_SAVED"
+  /** Cloud transcription was attempted and threw. */
+  | "CLOUD_FAILED"
+  /** No cloud provider is connected for this owner. */
+  | "CLOUD_UNCONFIGURED"
+  /** Anything not yet classified. Prose is preserved; never retried blindly. */
+  | "UNKNOWN";
+
+/**
+ * Codes worth retrying automatically.
+ *
+ * Retrying anything else wastes a media fetch and an ffmpeg run to reach the
+ * same answer — `NO_AUDIO_SAVED` in particular is a measurement of the stored
+ * file, so no number of retries will find audio that was never captured.
+ */
+const RETRYABLE: ReadonlySet<TranscriptFailureCode> = new Set([
+  "TIMEOUT",
+  "EXTRACTION_FAILED",
+  "CLOUD_FAILED",
+]);
+
+export function isRetryableTranscriptFailure(
+  code: TranscriptFailureCode | null | undefined,
+): boolean {
+  return code != null && RETRYABLE.has(code);
+}
+
+/**
+ * The sentence shown to a person, derived from the code.
+ *
+ * Each says what happened and what the reader can do about it. None of them
+ * blames the recording for a capture setting — "no speech was detected" on a
+ * recording saved without audio was the single most common transcript failure
+ * in production, and it sent people looking for a microphone problem when the
+ * screen-share simply never included audio.
+ */
+export function transcriptFailureMessage(code: TranscriptFailureCode): string {
+  switch (code) {
+    case "NO_AUDIO_SAVED":
+      return "This recording has no audio track, so there was nothing to transcribe. Screen recordings only capture audio when you share tab or system audio, or record with a microphone.";
+    case "NO_AUDIO_TRACK":
+      return "The saved media has no audio stream, so there was nothing to transcribe.";
+    case "NO_SPEECH_DETECTED":
+      return "Audio was captured but no speech was found in it.";
+    case "FFMPEG_UNAVAILABLE":
+      return "Audio could not be prepared for transcription because ffmpeg is unavailable on the server.";
+    case "EXTRACTION_FAILED":
+      return "Audio could not be prepared for transcription. Retrying usually works.";
+    case "TIMEOUT":
+      return "Transcription timed out before it finished. Retrying usually works.";
+    case "CLOUD_FAILED":
+      return "No transcript was captured locally, and cloud transcription could not finish. Retrying usually works; if it persists, check the recording's audio and the Builder connection.";
+    case "CLOUD_UNCONFIGURED":
+      return "No transcript was captured locally, and no cloud transcription provider is connected. Connect Builder in Settings to transcribe automatically.";
+    case "UNKNOWN":
+      return "Transcription did not finish.";
+  }
+}

package/corpus/templates/content/.agents/skills/actions/SKILL.md

@@ -20,6 +20,24 @@ Before creating any custom REST/API route for app data, inspect `actions/` and t
 
 **Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
 
+## Keep actions deterministic and composable
+
+An action may call a provider API, validate or normalize data, and persist
+records without being an AI feature. Keep those operations deterministic,
+focused, and independently useful to the agent. Do not put LLM calls or a
+second model runtime in ordinary actions. The only narrow exception is the
+`completeText()` text-in/text-out escape hatch described in
+`delegate-to-agent`; it must not own tools, chat history, run state, side
+effects, or user steering.
+
+When a workflow is framed as research, analysis, generation, recommendation,
+or synthesis, or spans several provider calls and writes, route the user into
+the AgentSidebar and let the agent orchestrate focused actions. Do not hide an
+AI-shaped workflow behind one opaque `generate-*` or `create-*` action just
+because its implementation is deterministic. A visible user-initiated run
+should use `sendToAgentChat({ openSidebar: true })`, and its follow-ups should
+continue in the same thread rather than a separate freeform input.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.

package/corpus/templates/content/.agents/skills/agent-native-toolkit/SKILL.md

@@ -56,6 +56,11 @@ The repeated app shell has two distinct navigation surfaces:
   labeled as local, preview, or analyze. For original/generated review, stack
   the source above the result by default and use side-by-side only for short,
   highly scannable content.
+- Deterministic implementation does not make an AI-shaped experience
+  deterministic. If the user expects research, analysis, generation,
+  recommendation, synthesis, visible progress, or steering, route the button
+  to the AgentSidebar and let the agent call focused actions. Keep revisions in
+  the same thread instead of adding a second freeform prompt box.
 - Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
   context. Match direct assistant-ui pins to the installed core/toolkit peer
   graph, use Vite dedupe/aliases when linked dependencies can split contexts,