@agent-native/core 0.79.26 → 0.80.0

package/corpus/templates/clips/changelog/2026-06-28-video-uploads-now-finish-when-duration-metadata-is-unavailable.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-28
+---
+
+Video uploads now finish even when the browser cannot read exact duration metadata.

package/corpus/templates/clips/desktop/src/lib/personal-vocabulary.ts

@@ -21,7 +21,7 @@
 
 import { invoke } from "@tauri-apps/api/core";
 
-interface VocabularyEntry {
+export interface VocabularyEntry {
   id: string;
   term: string;
   replacement: string;
@@ -37,13 +37,9 @@ export function configureVocabularyClient(url: string): void {
   serverUrl = url.replace(/\/+$/, "");
 }
 
-/**
- * Fetch the current user's vocabulary from the server. Cached for 60s so
- * the dictation start path stays snappy on rapid Fn re-presses.
- */
-export async function loadVocabulary(): Promise<string[]> {
+export async function loadVocabularyEntries(): Promise<VocabularyEntry[]> {
   if (cachedVocabulary && Date.now() - cachedAt < 60_000) {
-    return cachedVocabulary.map((v) => v.replacement);
+    return cachedVocabulary;
   }
   if (!serverUrl) return [];
   try {
@@ -55,13 +51,22 @@ export async function loadVocabulary(): Promise<string[]> {
     const data = (await res.json()) as { vocabulary?: VocabularyEntry[] };
     cachedVocabulary = data.vocabulary ?? [];
     cachedAt = Date.now();
-    return cachedVocabulary.map((v) => v.replacement);
+    return cachedVocabulary;
   } catch (err) {
     console.warn("[personal-vocabulary] loadVocabulary failed:", err);
     return [];
   }
 }
 
+/**
+ * Fetch the current user's vocabulary from the server. Cached for 60s so
+ * the dictation start path stays snappy on rapid Fn re-presses.
+ */
+export async function loadVocabulary(): Promise<string[]> {
+  const vocabulary = await loadVocabularyEntries();
+  return vocabulary.map((v) => v.replacement);
+}
+
 /**
  * Token-level diff between two short strings. Returns the first
  * `{term, replacement}` pair where a single word changed and length didn't

package/corpus/templates/clips/desktop/src/lib/transcription-engine.ts

@@ -101,10 +101,14 @@ function normalizeSource(source: unknown): TranscriptSource {
   return source === "system" ? "system" : "mic";
 }
 
-function locale(): string {
+function browserLocale(): string {
   return navigator.language || "en-US";
 }
 
+export function recordingTranscriptionLanguage(): string | null {
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Engine lifecycle
 // ---------------------------------------------------------------------------
@@ -119,14 +123,14 @@ export async function restartTranscriptionEngine(
   if (engine === "whisper") {
     await invoke("audio_transcription_start", {
       meetingId: null,
-      locale: locale(),
+      locale: recordingTranscriptionLanguage(),
       micDeviceId: mic?.deviceId || null,
       micDeviceLabel: mic?.label || null,
       captureSystem,
     });
   } else {
     await invoke("native_speech_start", {
-      locale: locale(),
+      locale: browserLocale(),
       micDeviceId: mic?.deviceId || null,
       micDeviceLabel: mic?.label || null,
     });

package/corpus/templates/clips/desktop/src/lib/voice-dictation.ts

@@ -1,3 +1,4 @@
+import type { VoiceContextPack } from "@agent-native/core/voice";
 import { invoke } from "@tauri-apps/api/core";
 import { emit, listen } from "@tauri-apps/api/event";
 
@@ -5,6 +6,7 @@ import { applyBacktrack } from "./backtrack";
 import {
   configureVocabularyClient,
   loadVocabulary,
+  loadVocabularyEntries,
   recordPasteForLearn,
 } from "./personal-vocabulary";
 import {
@@ -312,6 +314,7 @@ async function transcribe(
   providerPref: ServerVoiceProvider,
   controller: AbortController,
   instructions?: string,
+  contextPack?: VoiceContextPack,
 ): Promise<string> {
   const audioBlob = new Blob(chunks, { type: mimeType });
   const form = new FormData();
@@ -329,6 +332,7 @@ async function transcribe(
   if (trimmedInstructions) {
     form.append("instructions", trimmedInstructions);
   }
+  appendVoiceContext(form, contextPack);
   // Aggressive timeout — short clips should transcribe in well under
   // 2 seconds with Gemini Flash Lite or Whisper. If the server hasn't
   // come back in 8s it's hanging; abort and let the bar dismiss with an
@@ -367,6 +371,7 @@ async function cleanupTranscript(
   providerPref: ServerVoiceProvider,
   controller: AbortController,
   instructions?: string,
+  contextPack?: VoiceContextPack,
 ): Promise<string> {
   const form = new FormData();
   form.append("text", text);
@@ -375,6 +380,7 @@ async function cleanupTranscript(
   if (trimmedInstructions) {
     form.append("instructions", trimmedInstructions);
   }
+  appendVoiceContext(form, contextPack);
 
   const timeout = window.setTimeout(() => controller.abort(), 8_000);
   try {
@@ -400,6 +406,18 @@ async function cleanupTranscript(
   }
 }
 
+function appendVoiceContext(
+  form: FormData,
+  contextPack: VoiceContextPack | undefined,
+): void {
+  if (!contextPack) return;
+  try {
+    form.append("voiceContext", JSON.stringify(contextPack));
+  } catch {
+    /* best effort */
+  }
+}
+
 export function installDesktopVoiceDictation(
   options: DesktopVoiceDictationOptions,
 ): () => void {
@@ -640,6 +658,7 @@ export function installDesktopVoiceDictation(
       const controller = new AbortController();
       target.transcribeAbort = controller;
       try {
+        const contextPack = await buildDesktopVoiceContextPack();
         text =
           (await cleanupTranscript(
             serverUrl,
@@ -647,6 +666,7 @@ export function installDesktopVoiceDictation(
             target.cleanupProvider,
             controller,
             instructions,
+            contextPack,
           )) || original;
       } catch (err) {
         if ((err as { name?: string })?.name !== "AbortError") {
@@ -709,6 +729,42 @@ export function installDesktopVoiceDictation(
     micDeviceLabel: micDeviceLabel || null,
   });
 
+  const buildDesktopVoiceContextPack = async (): Promise<
+    VoiceContextPack | undefined
+  > => {
+    const vocabulary = await loadVocabularyEntries().catch(() => []);
+    const terms = vocabulary.map((entry) => ({
+      term: entry.term,
+      replacement: entry.replacement,
+      confidence: entry.confidence,
+      source: "learned-correction",
+      scope: "user",
+    }));
+    const snippets: NonNullable<VoiceContextPack["snippets"]> = [
+      { label: "Target surface", value: "Desktop dictation paste" },
+    ];
+    if (micDeviceLabel) {
+      snippets.push({ label: "Microphone", value: micDeviceLabel });
+    }
+    if (instructions.trim()) {
+      snippets.push({
+        label: "Saved voice instructions",
+        value: instructions.trim().slice(0, 1200),
+      });
+    }
+    return {
+      surface: "clips-desktop",
+      mode: "dictation",
+      snippets,
+      terms,
+      metadata: {
+        provider,
+        locale: navigator.language || "en-US",
+        micDeviceLabel: micDeviceLabel || null,
+      },
+    };
+  };
+
   /**
    * Server-path: capture audio with MediaRecorder, POST it to the
    * transcribe-voice endpoint on Fn-up, paste the response text. The
@@ -790,6 +846,7 @@ export function installDesktopVoiceDictation(
         const controller = new AbortController();
         next.transcribeAbort = controller;
         try {
+          const contextPack = await buildDesktopVoiceContextPack();
           const text = await transcribe(
             serverUrl,
             next.chunks,
@@ -797,6 +854,7 @@ export function installDesktopVoiceDictation(
             providerPref,
             controller,
             instructions,
+            contextPack,
           );
           if (next.cancelled) {
             cleanup(next);
@@ -920,7 +978,8 @@ export function installDesktopVoiceDictation(
         // metadata to `native_speech_start` without also carrying vocabulary.
         // Best-effort — if the load failed we just stage an empty list and
         // the recognizer behaves as before.
-        const contextualStrings = await loadVocabulary().catch(() => []);
+        const vocabularyEntries = await loadVocabularyEntries().catch(() => []);
+        const contextualStrings = vocabularyEntries.map((v) => v.replacement);
         await invoke("native_speech_set_vocabulary", {
           strings: contextualStrings,
         }).catch(() => {});

package/corpus/templates/clips/desktop/src-tauri/src/native_screen.rs

@@ -756,23 +756,25 @@ pub async fn native_fullscreen_recording_stop_and_upload(
     has_camera: bool,
 ) -> Result<NativeFullscreenUploadResult, String> {
     emit_native_upload_progress(&app, "finalizing", "Optimizing clip", None, None);
+    // The recorder's ScreenCaptureKit stream is now fully stopped and its moov
+    // atom is written (or has definitively failed). Signal the UI so it can tear
+    // down the separate live-transcription SCStream (system_audio.rs) now,
+    // without racing the recorder finalize: tearing that stream down while the
+    // recorder is still writing its moov interrupts ScreenCaptureKit
+    // (RPRecordingErrorDomain -5814) and corrupts the clip. We emit from inside
+    // the finalize helper — after the moov write but BEFORE segment
+    // consolidation — so a paused multi-segment recording stops transcription
+    // promptly instead of letting it run through the merge window and push the
+    // saved transcript past the clip's real end. See recorder.ts `handle.stop()`.
     let StoppedSession {
         session,
         duration_ms,
         stop_outcome,
         consolidate_outcome,
         multi_segment,
-    } = take_and_finalize_active_session(&state)?;
-
-    // The recorder's ScreenCaptureKit stream is now fully stopped and its moov
-    // atom is written (or has definitively failed). Signal the UI so it can tear
-    // down the separate live-transcription SCStream (system_audio.rs) now,
-    // without racing the recorder finalize: tearing that stream down while the
-    // recorder is still writing its moov interrupts ScreenCaptureKit
-    // (RPRecordingErrorDomain -5814) and corrupts the clip. Emitting here, before
-    // the slow upload, lets transcription stop promptly while the clip duration
-    // stays anchored to the real Stop click. See recorder.ts `handle.stop()`.
-    let _ = app.emit("clips:native-recording-finalized", &recording_id);
+    } = take_and_finalize_active_session(&state, |_session| {
+        let _ = app.emit("clips:native-recording-finalized", &recording_id);
+    })?;
 
     // The camera bubble is the ONE overlay we deliberately leave
     // capture-included (see `show_bubble`), so it has to stay on-screen
@@ -906,7 +908,7 @@ pub async fn native_fullscreen_recording_stop_and_save(
         stop_outcome,
         consolidate_outcome,
         multi_segment,
-    } = take_and_finalize_active_session(&state)?;
+    } = take_and_finalize_active_session(&state, |_session| {})?;
     // Capture is finalized — drop the camera bubble now so the face
     // doesn't linger while the clip saves (mirrors the upload path).
     let _ = crate::clips::close_bubble(app.clone()).await;
@@ -1207,8 +1209,17 @@ struct StoppedSession {
 /// Take the active session out of state, finalize its backend, and merge
 /// any pause/resume segments into the canonical output path. Shared by
 /// the upload and save-locally stop commands.
+///
+/// `on_capture_finalized` runs in the narrow window after the capture
+/// backend is fully stopped (moov atom written) but before segment
+/// consolidation begins. The upload path uses it to tell the UI to stop
+/// live transcription: doing it here keeps the saved transcript anchored
+/// to the clip's real end instead of running through the (multi-segment)
+/// merge, while still avoiding the -5814 corruption from tearing the
+/// transcription SCStream down before the recorder's moov is written.
 fn take_and_finalize_active_session(
     state: &State<'_, NativeFullscreenRecordingState>,
+    on_capture_finalized: impl FnOnce(&NativeFullscreenSession),
 ) -> Result<StoppedSession, String> {
     let mut session = {
         let mut guard = state.inner.lock().map_err(|e| e.to_string())?;
@@ -1233,6 +1244,13 @@ fn take_and_finalize_active_session(
         stop_outcome.is_ok(),
         describe_recording_path(&session.path)
     );
+    // The capture backend is fully stopped and its moov atom is written.
+    // Signal callers now — before the (potentially slow) segment merge — so
+    // live transcription can stop while the clip duration is still anchored
+    // to the real Stop click. Tearing it down here is safe from the -5814
+    // corruption because the recorder's SCStream is already finalized; the
+    // remaining work is plain on-disk file merging.
+    on_capture_finalized(&session);
     // With one segment this is a cheap rename. With multiple segments a
     // failure would silently lose everything after the first pause, so
     // callers check `multi_segment` and surface the merge error.

package/corpus/templates/clips/desktop/src-tauri/src/whisper_speech.rs

@@ -94,7 +94,7 @@ mod macos {
 
     use crate::native_speech::macos::{start_raw_mic_capture, RawMicCapture};
     use crate::system_audio::macos::{start_raw_system_capture, RawSystemCapture};
-    use crate::whisper_model::{custom_model_override, ensure_model, model_file};
+    use crate::whisper_model::{ensure_model, model_file};
 
     /// One transcript segment with real timestamps from whisper, already
     /// offset onto the meeting timeline (ms since capture start).
@@ -537,24 +537,11 @@ mod macos {
             msg
         })?;
 
-        // Custom/multilingual models always get auto-detect regardless of the
-        // supplied locale — forcing "en" onto a multilingual model when the
-        // meeting is in another language produces poor transcripts. The bundled
-        // ggml-base.en ignores the language field entirely, so forcing "en" is
-        // only useful for it (and harmless for other en-only models).
-        let lang: Option<String> = if custom_model_override() {
-            None
-        } else {
-            match language.as_deref() {
-                Some(l) if !l.trim().is_empty() => Some(
-                    l.split(['-', '_'])
-                        .next()
-                        .unwrap_or("en")
-                        .to_ascii_lowercase(),
-                ),
-                _ => Some("en".to_string()),
-            }
-        };
+        // Recording language should follow the spoken audio, not the UI/browser
+        // locale. The bundled ggml-base model is multilingual, so let
+        // whisper.cpp detect the language for every recording/meeting stream.
+        let _ = language;
+        let lang: Option<String> = None;
 
         // Mic stream + capture. The real hardware rate is read back from the
         // capture handle and pushed into the stream (default 48 kHz until then).

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -19,6 +19,7 @@ import {
   writeAppState,
 } from "@agent-native/core/application-state";
 import { runWithRequestContext } from "@agent-native/core/server";
+import { normalizeChunkUploadNumber } from "@shared/recording-core.js";
 import { MAX_UPLOAD_BYTES as MAX_RECORDING_UPLOAD_BYTES } from "@shared/upload-limits.js";
 import { and, eq } from "drizzle-orm";
 import {
@@ -405,9 +406,9 @@ export default defineEventHandler(async (event: H3Event) => {
       try {
         const result = await finalizeRecording.run({
           id: recordingId,
-          durationMs: query.durationMs ? Number(query.durationMs) : undefined,
-          width: query.width ? Number(query.width) : undefined,
-          height: query.height ? Number(query.height) : undefined,
+          durationMs: normalizeChunkUploadNumber(query.durationMs),
+          width: normalizeChunkUploadNumber(query.width),
+          height: normalizeChunkUploadNumber(query.height),
           hasAudio:
             query.hasAudio === undefined
               ? undefined

package/corpus/templates/clips/shared/builder-credits.ts

@@ -0,0 +1,120 @@
+export const CLIPS_BUILDER_CREDITS_STATE_KEY = "clips-builder-credits";
+
+export const BUILDER_CREDITS_UPGRADE_URL =
+  "https://builder.io/account/subscription?signupSource=agent-native&agentNativeConnectSource=clips_builder_credits&agentNativeFlow=connect_llm&framework=agent-native";
+
+export const BUILDER_CREDIT_FEATURES = [
+  "backup-transcription",
+  "cleanup",
+  "summaries",
+  "titles",
+] as const;
+
+export type BuilderCreditFeature = (typeof BUILDER_CREDIT_FEATURES)[number];
+
+export type BuilderCreditsSource =
+  | "transcription"
+  | "cleanup"
+  | "summary"
+  | "title";
+
+export interface BuilderCreditsStatus {
+  exhausted: boolean;
+  source?: BuilderCreditsSource;
+  message?: string;
+  upgradeUrl: string;
+  updatedAt?: string;
+  features: BuilderCreditFeature[];
+}
+
+const BUILDER_CREDITS_SOURCES = new Set<BuilderCreditsSource>([
+  "transcription",
+  "cleanup",
+  "summary",
+  "title",
+]);
+
+export function isBuilderCreditsExhaustedMessage(
+  reason: string | null | undefined,
+): boolean {
+  if (!reason) return false;
+  const normalized = reason.toLowerCase();
+  return (
+    normalized.includes("builder transcription credits exhausted") ||
+    normalized.includes("credits-limit") ||
+    normalized.includes("credit limit") ||
+    normalized.includes("credits limit") ||
+    normalized.includes("monthly ai credits") ||
+    normalized.includes("daily ai credits") ||
+    normalized.includes("builder.io plan") ||
+    (normalized.includes("builder") && normalized.includes("credits"))
+  );
+}
+
+export function createBuilderCreditsExhaustedStatus({
+  source,
+  message,
+  now = new Date().toISOString(),
+}: {
+  source: BuilderCreditsSource;
+  message: string;
+  now?: string;
+}): BuilderCreditsStatus {
+  return {
+    exhausted: true,
+    source,
+    message,
+    upgradeUrl: BUILDER_CREDITS_UPGRADE_URL,
+    updatedAt: now,
+    features: [...BUILDER_CREDIT_FEATURES],
+  };
+}
+
+export function emptyBuilderCreditsStatus(): BuilderCreditsStatus {
+  return {
+    exhausted: false,
+    upgradeUrl: BUILDER_CREDITS_UPGRADE_URL,
+    features: [...BUILDER_CREDIT_FEATURES],
+  };
+}
+
+export function normalizeBuilderCreditsStatus(
+  value: unknown,
+): BuilderCreditsStatus {
+  if (!value || typeof value !== "object") {
+    return emptyBuilderCreditsStatus();
+  }
+
+  const raw = value as Record<string, unknown>;
+  if (raw.exhausted !== true) {
+    return emptyBuilderCreditsStatus();
+  }
+
+  const source =
+    typeof raw.source === "string" &&
+    BUILDER_CREDITS_SOURCES.has(raw.source as BuilderCreditsSource)
+      ? (raw.source as BuilderCreditsSource)
+      : "transcription";
+
+  const message =
+    typeof raw.message === "string" && raw.message.trim()
+      ? raw.message
+      : "Builder.io credits are paused.";
+
+  const updatedAt =
+    typeof raw.updatedAt === "string" && raw.updatedAt.trim()
+      ? raw.updatedAt
+      : undefined;
+
+  return {
+    exhausted: true,
+    source,
+    message,
+    upgradeUrl:
+      typeof raw.upgradeUrl === "string" && raw.upgradeUrl.trim()
+        ? raw.upgradeUrl
+        : BUILDER_CREDITS_UPGRADE_URL,
+    updatedAt,
+    features: [...BUILDER_CREDIT_FEATURES],
+  };
+}

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

@@ -54,13 +54,30 @@ export type ChunkUploadParams = {
   total?: number;
   isFinal?: boolean;
   mimeType?: string;
-  durationMs?: number;
-  width?: number;
-  height?: number;
+  durationMs?: number | null;
+  width?: number | null;
+  height?: number | null;
   hasAudio?: boolean;
   hasCamera?: boolean;
 };
 
+export function normalizeChunkUploadNumber(value: unknown): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw === null || raw === undefined) return undefined;
+
+  const numberValue =
+    typeof raw === "number"
+      ? raw
+      : typeof raw === "string" && raw.trim()
+        ? Number(raw)
+        : undefined;
+
+  if (typeof numberValue !== "number" || !Number.isFinite(numberValue)) {
+    return undefined;
+  }
+  return Math.max(0, Math.round(numberValue));
+}
+
 /** Encode {@link ChunkUploadParams} as the chunk-upload query string. Booleans
  * become `1`/`0` and `durationMs` is rounded — matching what the route parses. */
 export function chunkUploadQuery(params: ChunkUploadParams): string {
@@ -69,11 +86,12 @@ export function chunkUploadQuery(params: ChunkUploadParams): string {
   if (params.total !== undefined) q.set("total", String(params.total));
   q.set("isFinal", params.isFinal ? "1" : "0");
   if (params.mimeType) q.set("mimeType", params.mimeType);
-  if (params.durationMs !== undefined) {
-    q.set("durationMs", String(Math.round(params.durationMs)));
-  }
-  if (params.width !== undefined) q.set("width", String(params.width));
-  if (params.height !== undefined) q.set("height", String(params.height));
+  const durationMs = normalizeChunkUploadNumber(params.durationMs);
+  const width = normalizeChunkUploadNumber(params.width);
+  const height = normalizeChunkUploadNumber(params.height);
+  if (durationMs !== undefined) q.set("durationMs", String(durationMs));
+  if (width !== undefined) q.set("width", String(width));
+  if (height !== undefined) q.set("height", String(height));
   if (params.hasAudio !== undefined) {
     q.set("hasAudio", params.hasAudio ? "1" : "0");
   }

package/corpus/templates/content/AGENTS.md

@@ -92,6 +92,10 @@ cd templates/content && pnpm action <name> [args]
 | `list-documents`                            | `[--format json]`                                                                                                                        | List document metadata/tree; no full bodies                                                                                             |
 | `export-content-source`                     | `[--format json]`                                                                                                                        | Export editable docs as `content/*.mdx` source files                                                                                    |
 | `import-content-source`                     | `--files <json> [--dryRun true\|false]`                                                                                                  | Import `.md`/`.mdx` source files into editable docs                                                                                     |
+| `list-builder-docs`                         | `[--model docs-content\|blog-article] [--limit <n>]`                                                                                     | List Builder docs/blog entries available for `.builder.mdx` pull                                                                        |
+| `pull-builder-doc`                          | `--model <model> --entryId <builder-entry-id> [--dryRun true\|false]`                                                                    | Pull one Builder entry into Content and return `.builder.mdx` plus `content/builder/.raw` sidecar files                                 |
+| `check-builder-doc`                         | `--files <json> [--path <file.builder.mdx>]` or `--documentId <id>`                                                                      | Validate Builder MDX round-trip, sidecar hashes, and remote conflict status before push                                                 |
+| `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                      | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                         |
 | `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                            | Open a route, document page, or database page in the UI                                                                                 |
 | `search-documents`                          | `--query <text> [--format json]`                                                                                                         | Search by title/content and return snippets                                                                                             |
 | `get-document`                              | `--id <id> [--format json]`                                                                                                              | Get a single document with content                                                                                                      |
@@ -178,6 +182,10 @@ Content has two file workflows:
   `update-document` writes the selected `.md`/`.mdx` file. The document id is
   derived from the file path, and unknown frontmatter is preserved when title,
   content, icon, or favorite state changes.
+  Repos can opt into `profile: "docs/no-bookkeeping"` to keep docs edits from
+  adding absent `updatedAt`, `icon`, or `isFavorite` frontmatter. Content-only
+  edits under that profile preserve existing frontmatter but do not create new
+  bookkeeping keys; explicit title/icon/favorite edits still persist.
 - **Local MDX components:** local file workspaces can expose React components
   from the configured `components` folder. Export PascalCase components such as
   `ImpactCounter` from `.tsx` files, then use `<ImpactCounter />` in MDX or pick
@@ -204,11 +212,17 @@ Minimal `agent-native.json`:
 ```json
 {
   "version": 1,
-  "mode": "local-files",
   "apps": {
     "content": {
+      "mode": "local-files",
+      "profile": "docs/no-bookkeeping",
       "roots": [
-        { "name": "Docs", "path": "docs", "extensions": [".md", ".mdx"] },
+        {
+          "name": "Docs",
+          "path": "docs",
+          "profile": "docs/no-bookkeeping",
+          "extensions": [".md", ".mdx"]
+        },
         { "name": "Blog", "path": "blog", "extensions": [".md", ".mdx"] },
         {
           "name": "Resources",
@@ -222,6 +236,13 @@ Minimal `agent-native.json`:
 }
 ```
 
+Launch Content directly against a local folder or file with:
+
+```bash
+agent-native content local-files docs --profile docs/no-bookkeeping
+agent-native content local-files docs/guide.mdx --profile docs/no-bookkeeping
+```
+
 In Local File Mode, use the normal document actions (`list-documents`,
 `get-document`, `create-document`, `update-document`, `delete-document`) instead
 of raw filesystem writes when operating through the app. To share a local file,