@agent-native/core 0.137.8 → 0.138.0

package/corpus/templates/clips/app/components/player/video-player.tsx

@@ -28,6 +28,7 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { Spinner } from "@/components/ui/spinner";
 import { useMseVideoSource } from "@/hooks/use-mse-video-source";
+import { usePlaybackPosition } from "@/hooks/use-playback-position";
 import {
   parsePlaybackSpeed,
   readPlaybackSpeedPreference,
@@ -265,9 +266,12 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       [videoUrl],
     );
     const videoRef = useRef<HTMLVideoElement | null>(null);
+    const [playbackVideoEl, setPlaybackVideoEl] =
+      useState<HTMLVideoElement | null>(null);
     const setVideoNode = useCallback(
       (el: HTMLVideoElement | null) => {
         videoRef.current = el;
+        setPlaybackVideoEl(el);
         onVideoElementChange?.(el);
       },
       [onVideoElementChange],
@@ -408,6 +412,50 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       () => embedProvider === "loom" || isLoomEmbedUrl(activeVideoSrc),
       [activeVideoSrc, embedProvider],
     );
+    const restorePlaybackPosition = useCallback(
+      (positionMs: number) => {
+        const v = videoRef.current;
+        if (!v || (startMs && startMs > 0)) return;
+        if (hasPlaybackStarted && !autoPlay) return;
+        if (!autoPlay && isPlayPending) return;
+        if (!autoPlay && v.currentTime > 0.5) return;
+
+        const visibleMs = clampSeek(
+          skipExcludedRange(positionMs, excludedRanges, resolvedDurationMs),
+          v,
+          resolvedDurationMs,
+        );
+        if (visibleMs <= 0) return;
+
+        try {
+          initialVisibleFrameSeekedRef.current = true;
+          v.currentTime = visibleMs / 1000;
+          setCurrentMs(visibleMs);
+          setCanPlay(true);
+          setIsPreparing(false);
+          onTimeUpdate?.(visibleMs, resolvedDurationMs);
+        } catch (error) {
+          console.warn("[clips] playback position restore failed", error);
+        }
+      },
+      [
+        autoPlay,
+        excludedRanges,
+        hasPlaybackStarted,
+        isPlayPending,
+        onTimeUpdate,
+        resolvedDurationMs,
+        startMs,
+      ],
+    );
+    usePlaybackPosition({
+      recordingId,
+      videoEl: playbackVideoEl,
+      durationMs,
+      explicitStartMs: startMs,
+      allowRestoreWhilePlaying: autoPlay,
+      onRestore: restorePlaybackPosition,
+    });
     // Clips stores exactly one `videoUrl` per recording (no alternate-format
     // fallback to select between), and every browser MediaRecorder-based
     // recording is stored as `webm` — which Safari (desktop and iOS) cannot
@@ -1291,11 +1339,12 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
           ? "loading"
           : "ready"
         : null;
-    const centerOverlayLabel = isPlayPending
-      ? "Starting playback"
-      : isBuffering
-        ? "Buffering"
-        : "Preparing clip";
+    const centerOverlayLabel =
+      isPlayPending && !hasPlaybackStarted
+        ? "Starting playback"
+        : isPlayPending || isBuffering
+          ? "Buffering"
+          : "Preparing clip";
 
     return (
       <div

package/corpus/templates/clips/app/hooks/use-playback-position.ts

@@ -0,0 +1,188 @@
+import { useEffect, useRef } from "react";
+
+import {
+  getPlaybackPosition,
+  savePlaybackPosition,
+} from "@/lib/playback-position";
+
+const SAVE_INTERVAL_MS = 5_000;
+const MIN_POSITION_MS = 50;
+const COMPLETION_TAIL_MS = 1_500;
+
+export interface UsePlaybackPositionOptions {
+  recordingId: string;
+  videoEl: HTMLVideoElement | null;
+  durationMs: number;
+  explicitStartMs?: number;
+  allowRestoreWhilePlaying?: boolean;
+  onRestore?: (positionMs: number) => void;
+}
+
+/**
+ * Persists the latest native-video position for the current viewer. This is
+ * separate from view analytics so the recording owner can resume without
+ * becoming one of the clip's counted viewers.
+ */
+export function usePlaybackPosition({
+  recordingId,
+  videoEl,
+  durationMs,
+  explicitStartMs,
+  allowRestoreWhilePlaying = false,
+  onRestore,
+}: UsePlaybackPositionOptions) {
+  const durationMsRef = useRef(durationMs);
+  const onRestoreRef = useRef(onRestore);
+
+  durationMsRef.current = durationMs;
+  onRestoreRef.current = onRestore;
+
+  useEffect(() => {
+    if (!videoEl || !recordingId) return;
+
+    const controller = new AbortController();
+    let cancelled = false;
+    let playbackStarted = false;
+    let restoreApplied = false;
+    let saveInFlight = false;
+    let pendingSave: { positionMs: number; keepalive: boolean } | null = null;
+    let lastSavedPositionMs = -1;
+    let lastSavedAt = -SAVE_INTERVAL_MS;
+    let removePendingRestoreListeners: (() => void) | null = null;
+
+    const readPositionMs = (): number | null => {
+      const seconds = videoEl.currentTime;
+      if (!Number.isFinite(seconds) || seconds < 0 || seconds >= 1e7) {
+        return null;
+      }
+      return Math.floor(seconds * 1000);
+    };
+
+    const persist = (keepalive: boolean) => {
+      const positionMs = readPositionMs();
+      if (
+        positionMs === null ||
+        (!playbackStarted && positionMs < MIN_POSITION_MS)
+      ) {
+        return;
+      }
+
+      const now = Date.now();
+      if (!keepalive && now - lastSavedAt < SAVE_INTERVAL_MS) {
+        return;
+      }
+
+      if (saveInFlight) {
+        pendingSave = { positionMs, keepalive };
+        return;
+      }
+
+      saveInFlight = true;
+      lastSavedPositionMs = positionMs;
+      lastSavedAt = now;
+      void savePlaybackPosition(recordingId, positionMs, { keepalive })
+        .catch((error) => {
+          if (!cancelled) {
+            console.warn("[clips] playback position save failed", error);
+          }
+        })
+        .finally(() => {
+          saveInFlight = false;
+          if (!pendingSave) return;
+          const next = pendingSave;
+          pendingSave = null;
+          persist(next.keepalive);
+        });
+    };
+
+    const restore = (positionMs: number) => {
+      if (cancelled || restoreApplied || explicitStartMs) return;
+      if (positionMs <= 0) return;
+      const duration = durationMsRef.current;
+      if (duration > 0 && positionMs >= duration - COMPLETION_TAIL_MS) {
+        return;
+      }
+      if (
+        playbackStarted &&
+        !allowRestoreWhilePlaying &&
+        readPositionMs() !== 0
+      ) {
+        return;
+      }
+
+      restoreApplied = true;
+      onRestoreRef.current?.(positionMs);
+    };
+
+    const restoreWhenReady = (positionMs: number) => {
+      if (videoEl.readyState >= 1) {
+        restore(positionMs);
+        return;
+      }
+
+      const apply = () => {
+        removePendingRestoreListeners?.();
+        removePendingRestoreListeners = null;
+        restore(positionMs);
+      };
+      videoEl.addEventListener("loadedmetadata", apply);
+      videoEl.addEventListener("loadeddata", apply);
+      removePendingRestoreListeners = () => {
+        videoEl.removeEventListener("loadedmetadata", apply);
+        videoEl.removeEventListener("loadeddata", apply);
+      };
+    };
+
+    const onPlay = () => {
+      playbackStarted = true;
+    };
+    const onTimeUpdate = () => {
+      if (playbackStarted) persist(false);
+    };
+    const onPause = () => persist(true);
+    const onSeeked = () => persist(true);
+    const onEnded = () => persist(true);
+    const onPageHide = () => persist(true);
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "hidden") persist(true);
+    };
+
+    videoEl.addEventListener("play", onPlay);
+    videoEl.addEventListener("timeupdate", onTimeUpdate);
+    videoEl.addEventListener("pause", onPause);
+    videoEl.addEventListener("seeked", onSeeked);
+    videoEl.addEventListener("ended", onEnded);
+    window.addEventListener("pagehide", onPageHide);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    if (!explicitStartMs) {
+      void getPlaybackPosition(recordingId, { signal: controller.signal })
+        .then((positionMs) => {
+          if (positionMs !== null) restoreWhenReady(positionMs);
+        })
+        .catch((error) => {
+          if (
+            !cancelled &&
+            (error as { name?: string })?.name !== "AbortError"
+          ) {
+            console.warn("[clips] playback position load failed", error);
+          }
+        });
+    }
+
+    return () => {
+      persist(true);
+      cancelled = true;
+      controller.abort();
+      removePendingRestoreListeners?.();
+      removePendingRestoreListeners = null;
+      videoEl.removeEventListener("play", onPlay);
+      videoEl.removeEventListener("timeupdate", onTimeUpdate);
+      videoEl.removeEventListener("pause", onPause);
+      videoEl.removeEventListener("seeked", onSeeked);
+      videoEl.removeEventListener("ended", onEnded);
+      window.removeEventListener("pagehide", onPageHide);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [allowRestoreWhilePlaying, explicitStartMs, recordingId, videoEl]);
+}

package/corpus/templates/clips/app/hooks/use-view-tracking.ts

@@ -1,27 +1,9 @@
 import { appBasePath } from "@agent-native/core/client/api-path";
 import { useEffect, useRef } from "react";
 
-import { clampCompletionPct } from "../../shared/view-analytics";
-
-const SESSION_KEY = "clips-view-session-id";
+import { getViewerSessionId } from "@/lib/viewer-session";
 
-function getSessionId(): string {
-  if (typeof window === "undefined") return "server";
-  try {
-    let id = localStorage.getItem(SESSION_KEY);
-    if (!id) {
-      id =
-        "s-" +
-        Date.now().toString(36) +
-        "-" +
-        Math.random().toString(36).slice(2, 8);
-      localStorage.setItem(SESSION_KEY, id);
-    }
-    return id;
-  } catch {
-    return "s-" + Math.random().toString(36).slice(2, 8);
-  }
-}
+import { clampCompletionPct } from "../../shared/view-analytics";
 
 function createViewSessionId(recordingId: string): string {
   return [
@@ -118,7 +100,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
           recordingId,
           kind: "view-start",
           timestampMs: 0,
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
           viewSessionId: viewSessionRef.current,
           totalWatchMs: 0,
           completedPct: 0,
@@ -130,7 +112,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
     }
 
     const video = videoEl;
-    const sessionId = getSessionId();
+    const sessionId = getViewerSessionId();
     viewSessionRef.current = createViewSessionId(recordingId);
     let progressTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -243,7 +225,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
         body: JSON.stringify({
           recordingId: recordingIdRef.current,
           kind: "cta-click",
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
         }),
       }).catch(() => {});
     },
@@ -255,7 +237,7 @@ export function useViewTracking(opts: UseViewTrackingOpts) {
         body: JSON.stringify({
           recordingId: recordingIdRef.current,
           kind: "reaction",
-          sessionId: getSessionId(),
+          sessionId: getViewerSessionId(),
           payload: { emoji },
         }),
       }).catch(() => {});

package/corpus/templates/clips/app/lib/playback-position.ts

@@ -0,0 +1,99 @@
+import {
+  callAction,
+  tryCallActionKeepalive,
+} from "@agent-native/core/client/hooks";
+
+import { getViewerSessionId } from "./viewer-session";
+
+export interface PlaybackPositionRecord {
+  recordingId: string;
+  viewerKey: string;
+  viewerEmail: string | null;
+  positionMs: number;
+  updatedAt: string | null;
+}
+
+interface PlaybackPositionActionResult {
+  playbackPosition: PlaybackPositionRecord | null;
+}
+
+function parsePlaybackPosition(payload: unknown): number | null {
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    !("playbackPosition" in payload)
+  ) {
+    throw new Error("Invalid playback position response");
+  }
+  const playbackPosition = (payload as { playbackPosition?: unknown })
+    .playbackPosition;
+  if (playbackPosition === null) return null;
+  if (typeof playbackPosition !== "object") {
+    throw new Error("Invalid playback position payload");
+  }
+  const positionMs = (playbackPosition as { positionMs?: unknown }).positionMs;
+  if (
+    typeof positionMs !== "number" ||
+    !Number.isFinite(positionMs) ||
+    positionMs < 0
+  ) {
+    throw new Error("Invalid playback position payload");
+  }
+  return positionMs;
+}
+
+export async function getPlaybackPosition(
+  recordingId: string,
+  options: {
+    sessionId?: string;
+    signal?: AbortSignal;
+  } = {},
+): Promise<number | null> {
+  const sessionId = options.sessionId ?? getViewerSessionId();
+  const payload = await callAction<PlaybackPositionActionResult>(
+    "get-playback-position",
+    { recordingId, sessionId },
+    { method: "GET", signal: options.signal },
+  );
+  return parsePlaybackPosition(payload);
+}
+
+export async function savePlaybackPosition(
+  recordingId: string,
+  positionMs: number,
+  options: {
+    sessionId?: string;
+    signal?: AbortSignal;
+    keepalive?: boolean;
+  } = {},
+): Promise<void> {
+  const sessionId = options.sessionId ?? getViewerSessionId();
+  const params = { recordingId, positionMs, sessionId };
+
+  if (options.keepalive) {
+    const request = tryCallActionKeepalive<PlaybackPositionActionResult>(
+      "save-playback-position",
+      params,
+      { signal: options.signal },
+    );
+    if (!request.accepted) {
+      throw new Error(
+        `Failed to save playback position during unload (${request.reason})`,
+      );
+    }
+    const payload = await request.completion;
+    if (parsePlaybackPosition(payload) === null) {
+      throw new Error("Invalid playback position payload");
+    }
+    return;
+  }
+
+  const payload = await callAction<PlaybackPositionActionResult>(
+    "save-playback-position",
+    params,
+    { signal: options.signal },
+  );
+  if (parsePlaybackPosition(payload) === null) {
+    throw new Error("Invalid playback position payload");
+  }
+}

package/corpus/templates/clips/app/lib/viewer-session.ts

@@ -0,0 +1,29 @@
+const VIEWER_SESSION_STORAGE_KEY = "clips-view-session-id";
+let inMemoryViewerSessionId: string | null = null;
+
+function fallbackSessionId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function getViewerSessionId(): string {
+  if (typeof window === "undefined") {
+    if (inMemoryViewerSessionId) return inMemoryViewerSessionId;
+    inMemoryViewerSessionId = fallbackSessionId();
+    return inMemoryViewerSessionId;
+  }
+
+  try {
+    const existing = window.localStorage.getItem(VIEWER_SESSION_STORAGE_KEY);
+    if (existing) return existing;
+    const next =
+      typeof window.crypto?.randomUUID === "function"
+        ? window.crypto.randomUUID()
+        : fallbackSessionId();
+    window.localStorage.setItem(VIEWER_SESSION_STORAGE_KEY, next);
+    return next;
+  } catch {
+    if (inMemoryViewerSessionId) return inMemoryViewerSessionId;
+    inMemoryViewerSessionId = fallbackSessionId();
+    return inMemoryViewerSessionId;
+  }
+}

package/corpus/templates/clips/changelog/2026-08-05-clip-buffering-now-uses-buffering-copy-after-playback.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-05
+---
+
+Clip buffering now shows buffering copy after playback starts.

package/corpus/templates/clips/changelog/2026-08-05-clips-remembers-your-playback-position-when-you-reopen-a-cli.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-05
+---
+
+Clips remembers your playback position when you reopen a clip.

package/corpus/templates/clips/learnings.defaults.md

@@ -24,7 +24,7 @@
 ## Meetings & Dictate
 
 - When a user says **"meeting"** they mean a Meetings tab entry, not a Clips recording — _unless_ the recording is linked to a meeting (i.e. `recordings.meeting_id` is non-null), in which case both interpretations are valid and worth mentioning.
-- When suggesting how to enable transcript improvements (cleanup, summary, action items), **lead with Builder.io Connect** — it's the easiest path and requires no key. Mention a BYOK `GEMINI_API_KEY` only as a secondary fallback. The cleanup pipeline does not use direct Groq or OpenAI keys by default; it prefers Luna through Builder or OpenAI, with Gemini as the fallback.
+- When suggesting how to enable transcript improvements (cleanup, summary, action items), **lead with Builder.io Connect** — its free tier is available, it's the easiest path, and it requires no key. Mention a BYOK `GEMINI_API_KEY` only as a secondary fallback. The cleanup pipeline does not use direct Groq or OpenAI keys by default; it prefers Luna through Builder or OpenAI, with Gemini as the fallback.
 - **Per-attendee action items require attendees to actually speak in the recorded audio.** With mic + system audio capture (Meetings default) both sides are heard and tagged by source. With mic-only capture (and all Dictate dictations), remote attendees may be silent in the transcript — call this out before promising attendee-level coverage.
 
 ## Platform requirements

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

@@ -404,6 +404,24 @@ export const recordingViews = table("recording_views", {
   viewedAt: text("viewed_at").notNull().default(now()),
 });
 
+export const recordingPlaybackPositions = table(
+  "recording_playback_positions",
+  {
+    id: text("id").primaryKey(),
+    recordingId: text("recording_id").notNull(),
+    viewerKey: text("viewer_key").notNull(),
+    viewerEmail: text("viewer_email"),
+    positionMs: integer("position_ms").notNull().default(0),
+    updatedAt: text("updated_at").notNull().default(now()),
+    createdAt: text("created_at").notNull().default(now()),
+  },
+  (position) => ({
+    recordingPlaybackPositionUnique: uniqueIndex(
+      "recording_playback_positions_recording_viewer_key_unique_idx",
+    ).on(position.recordingId, position.viewerKey),
+  }),
+);
+
 // Agent views — one row per (clip, agent, time bucket). Deliberately separate
 // from `recording_viewers` / `recording_views` so no human-view count can ever
 // pick agents up by forgetting a filter: the human tables stay agent-free.

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -506,7 +506,7 @@ export function transcriptStatusInstructions(
 
   if (status === "failed" && lowerReason.includes("credits exhausted")) {
     return [
-      "Transcription failed because Builder transcription credits are exhausted. Tell the user to upgrade or connect Builder.io credits. Clips uses the browser/macOS native transcript first and Builder transcription on the original recording when native capture is unavailable.",
+      "Transcription failed because Builder transcription credits are exhausted. Tell the user to upgrade or connect Builder.io credits (free tier available). Clips uses the browser/macOS native transcript first and Builder transcription on the original recording when native capture is unavailable.",
     ];
   }
 

package/corpus/templates/clips/server/lib/video-storage.ts

@@ -5,7 +5,7 @@ import {
 } from "@agent-native/core/server";
 
 export const STORAGE_SETUP_REQUIRED_REASON =
-  "Video storage is not connected yet. Connect Builder.io or configure S3-compatible storage to upload clips.";
+  "Video storage is not connected yet. Connect Builder.io (free tier available) or configure S3-compatible storage to upload clips.";
 
 function appDatabaseUrl(): string {
   const appName = process.env.APP_NAME?.toUpperCase().replace(/-/g, "_");

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

@@ -931,6 +931,21 @@ const migrations = runMigrations(
       // guard:allow-unscoped — startup migration normalizes a legacy placeholder across all rows.
       sql: `UPDATE recording_agent_views SET agent_label = NULL WHERE agent_label = 'Agent'`,
     },
+    {
+      version: 58,
+      name: "recording-playback-positions",
+      sql: `CREATE TABLE IF NOT EXISTS recording_playback_positions (
+      id TEXT PRIMARY KEY,
+      recording_id TEXT NOT NULL,
+      viewer_key TEXT NOT NULL,
+      viewer_email TEXT,
+      position_ms INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS recording_playback_positions_recording_viewer_key_unique_idx
+      ON recording_playback_positions (recording_id, viewer_key)`,
+    },
   ],
   { table: "clips_migrations" },
 );

package/corpus/templates/clips/server/routes/api/media/index.post.ts

@@ -26,7 +26,7 @@ import {
 const MAX_BYTES = 5 * 1024 * 1024;
 
 const STORAGE_SETUP_REQUIRED_REASON =
-  "File storage is not connected yet. Connect Builder.io or configure S3-compatible storage in Settings → File uploads, then retry.";
+  "File storage is not connected yet. Connect Builder.io (free tier available) or configure S3-compatible storage in Settings → File uploads, then retry.";
 
 function randId(): string {
   const chars =

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

@@ -31,6 +31,26 @@ the framework monorepo checkout.
 
 From a generated app directory:
 
+```bash
+pnpm action framework-search --pattern "defineAction"
+pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
+pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
+```
+
+Use `framework-search` first when a question may cross the docs and source
+boundary. It searches the version-matched framework docs, runtime-visible
+skills, readable Core or Toolkit package source, and first-party template
+corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
+narrow it, then use the existing focused readers for the page or file you need.
+
+The same tool is available in the headless `pnpm agent` loop and every built-in
+app agent. Its default substring mode is safest for ordinary questions; use
+`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
+for precise structural matches. Results are bounded, so refine the pattern or
+path instead of treating a truncated result as exhaustive.
+
+From a generated app directory, the lower-level readers remain available:
+
 ```bash
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
@@ -41,9 +61,9 @@ pnpm action source-search --path templates/chat/actions/hello.ts
 pnpm action source-search --list
 ```
 
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
+The headless `pnpm agent` loop and built-in app agent also expose read-only
+`framework-search`, `docs-search`, and `source-search` tools. Use the unified
+tool for discovery, then the focused tools for full page or file reads.
 
 If the action runner is unavailable, search the package directly:
 

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

@@ -65,6 +65,22 @@ Contextual agent UI is not a reason to expose every option at once. Start with
 the domain task's primary action, reveal review or configuration only when the
 current state needs it, and let the sidebar carry conversational depth.
 
+## Visual Direction And Workspace Variety
+
+Shared workspace behavior should be consistent without forcing every app into
+the same visual skin. Keep shell and component tokens semantic, then let each
+app declare a named direction in `DESIGN.md` before styling. A new app should
+choose its palette family and composition from the product context, compare
+nearby apps, and avoid inheriting their accent by default. Use the
+`frontend-design` visual-direction reference for mode, palette, type, density,
+shape, anti-references, and the `distill` / `typeset` / `colorize` / `layout` /
+`polish` / `audit` review vocabulary.
+
+Do not make warm beige plus terracotta the workspace fallback. Preserve a
+workspace-level brand when one exists; otherwise keep shared chrome neutral and
+allow app-owned accents to distinguish products while retaining accessible
+semantic states and the shared AgentSidebar contract.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/corpus/templates/content/.agents/skills/document-editing/references/databases.md

@@ -234,6 +234,19 @@ Use `create-content-database`, `create-inline-content-database`,
 `duplicate-document-property`, and `delete-document-property`; do not edit
 property rows or view config via raw SQL when an action can do it.
 
+For a bounded migration that must rewrite every existing row body while adding
+new property definitions and values, use `migrate-content-database-rows` rather
+than looping the single-row actions. Its `validate` phase is read-only; `apply`
+commits the complete plan with an idempotency receipt or writes nothing. Read
+the database and every row independently after apply, then call its separate
+`verify` phase with the saved post-apply digest. Only a verified receipt may
+`finalize` the exact legacy property IDs stored in that receipt. `rollback` is
+available before finalize only while the saved post-apply digest still matches,
+so it never overwrites a later edit. The bounded migration accepts ordinary
+databases without attached Sources; source-backed and system databases retain
+their dedicated synchronization actions. If flushing a live row editor changes
+its persisted revision, read the rows again and build a fresh plan.
+
 When targeting more than one database row, call `duplicate-database-items` or
 `remove-database-items` once with a native JSON array of `itemIds` or
 `documentIds`. Do not loop `duplicate-database-item` or `delete-document` for