@agent-native/core 0.80.1 → 0.80.4

package/corpus/core/src/cli/skills.ts

@@ -1405,8 +1405,10 @@ The local-files contract:
   \`id\` and \`label\`; and \`Code\` / \`AnnotatedCode\` / \`Diff\` are whitespace-sensitive
   — encode multiline code as JSON string attributes such as \`code={"const x =\\n  y"}\`
   (a static template literal is accepted only when it has no \`\${...}\`
-  interpolation). \`plan local check\` validates these required fields against the
-  renderer schema.
+  interpolation). \`plan local check\` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green \`check\` does not guarantee the plan renders;
+  \`plan local verify\` is the authoritative validation against the real renderer
+  schema.
 - **Write a local MDX folder.** Use \`plans/<slug>/\` to check the artifact into the
   repo, or a repo-ignored/temporary folder such as \`.agent-native/plans/<slug>/\`
   or \`/tmp/agent-native-plans/<slug>/\` when it should not be checked in. The
@@ -1431,9 +1433,16 @@ The local-files contract:
   running local Plan app.
 - **Headless verify.** Run
   \`npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>\`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the
-  \`bridgeUrl\` from the verify/serve JSON to read the concrete validation error.
+  It starts the bridge, checks the private-network preflight and JSON payload, AND
+  validates the content against the real renderer schema via the Plan app's
+  \`validate-local-plan-source\` action. A non-\`ok\` result with
+  \`validation.valid: false\` lists the renderer's exact schema-path issues (e.g.
+  \`blocks[1].data.tabs[0]...\`); fix those before handing off. If \`validation.ran\`
+  is \`false\`, the Plan app did not expose the validate endpoint (older/unreachable
+  deploy) — point \`--app-url\` at a current Plan app (e.g. a local
+  \`http://localhost:8096\`) for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the \`bridgeUrl\` from the verify/serve JSON to read the
+  concrete validation error.
 - **Never call hosted tools for that plan/recap.** Do not call
   \`create-visual-plan\`, \`create-ui-plan\`, \`create-prototype-plan\`,
   \`create-plan-design\`, \`create-visual-recap\`, \`create-visual-questions\`,

package/corpus/core/src/mcp/build-server.ts

@@ -750,7 +750,7 @@ function safeUiSegment(value: string | undefined, fallback: string): string {
 
 // ChatGPT and Claude cache MCP App resource HTML by `ui://` URI. Bump this
 // when the shared shell changes in a way that must invalidate host caches.
-const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v53";
+const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v54";
 
 function legacyDefaultMcpAppUri(config: MCPConfig, actionName: string): string {
   const app = safeUiSegment(config.appId ?? config.name, "agent-native");

package/corpus/core/src/mcp/embed-app.ts

@@ -124,6 +124,7 @@ export function embedApp(
     let app = null;
     let appConnectPromise = null;
     let openAiBridge = null;
+    let lastOpenAiSyncSignature = null;
     let wrapperRequestId = 0;
     const wrapperRequests = new Map();
     let toolInput = {};
@@ -1533,11 +1534,19 @@ export function embedApp(
         setMessage("Ready to open.");
         return;
       }
-      setMessage("Loading app");
       try {
         const selfNavigate = shouldSelfNavigateToApp();
         if (startedFor === launchUrl) return;
         startedFor = launchUrl;
+        // Only show the loading message when no frame is mounted yet. ChatGPT
+        // fires openai:set_globals (and thus re-launch) constantly; calling
+        // setMessage() unconditionally here wiped the just-mounted iframe out of
+        // the stage on every redundant launch, so the app rendered and was
+        // instantly blanked back to "Loading app" forever. renderFrame()/
+        // transplant replace the stage themselves when they actually (re)mount.
+        if (!appFrame) {
+          setMessage("Loading app");
+        }
         const embedUrl = withChatBridgeParam(launchUrl);
         if (selfNavigate && isEmbedStartUrl(embedUrl)) {
           if (shouldTransplantAppDocument()) {
@@ -1662,6 +1671,31 @@ export function embedApp(
       toolResultData = objectValue(data);
       openUrl = openLinkFrom(params, data);
       openStartUrl = embedStartUrlFrom(params, data);
+      // ChatGPT/Codex fire openai:set_globals extremely often, and the listener
+      // that calls this re-syncs on each one. Because this function calls
+      // notifyHostHeight()/sendHostContext() (which the host reflects back as a
+      // fresh set_globals), an unguarded sync becomes an infinite feedback storm
+      // that starves the host until it shows its sad-face placeholder. Only do
+      // the host round-trips + (re)launch when something we care about changed.
+      // Deliberately EXCLUDE bridge.maxHeight: the host mutates it on every
+      // set_globals as it echoes our height back, which would defeat the guard.
+      let signature;
+      try {
+        signature = JSON.stringify([
+          toolInput,
+          openUrl,
+          openStartUrl,
+          bridge.displayMode,
+          bridge.theme,
+          bridge.locale
+        ]);
+      } catch {
+        signature = null;
+      }
+      if (signature !== null && signature === lastOpenAiSyncSignature) {
+        return true;
+      }
+      lastOpenAiSyncSignature = signature;
       updateTitle(data);
       updateOpenButton();
       updateDisplayButton();

package/corpus/core/src/server/action-routes.ts

@@ -284,6 +284,20 @@ export function mountActionRoutes(
         return runWithRequestContext(
           { userEmail, userName, orgId, timezone },
           async () => {
+            // Reject oversize bodies from Content-Length before parsing, so a
+            // public no-auth POST can't force parse work on a huge request.
+            if (typeof entry.maxBodyBytes === "number" && method !== "GET") {
+              const clRaw = getHeader(event, "content-length");
+              if (clRaw) {
+                const declared = parseInt(clRaw, 10);
+                if (!Number.isNaN(declared) && declared > entry.maxBodyBytes) {
+                  setResponseStatus(event, 413);
+                  return {
+                    error: `Request body too large (max ${entry.maxBodyBytes} bytes)`,
+                  };
+                }
+              }
+            }
             // Parse params based on method. On web-standard runtimes (Netlify
             // Functions, CF Workers), event.req IS the web Request — use .json()
             // directly. H3's readBody fails on those runtimes because it expects

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

@@ -1087,7 +1087,21 @@ function baseRedirectGuard(): Plugin {
         if (serveMountedEmbedRuntimeModule(server, req, res, base)) {
           return;
         }
-        req.url = stripMountedDevApiPath(req.url, base);
+        // Nitro's pre-middleware only intercepts document/iframe/frame/empty
+        // fetch-dest requests. For video/audio/image etc. it calls next() and
+        // the post-internal Nitro middleware handles them instead. If we strip
+        // the base path here for those requests, Vite's base middleware sees the
+        // stripped path (e.g. /api/video/:id without /clips/) and responds with
+        // a "did you mean /clips/api/video/:id" error before Nitro can handle it.
+        // Only strip when the request type matches Nitro's pre-middleware gate.
+        const secFetchDest = req.headers["sec-fetch-dest"] as
+          | string
+          | undefined;
+        const isNitroPreHandled =
+          !secFetchDest || /^(document|iframe|frame|empty)$/.test(secFetchDest);
+        if (isNitroPreHandled) {
+          req.url = stripMountedDevApiPath(req.url, base);
+        }
         if (
           req.method === "HEAD" &&
           req.url &&

package/corpus/templates/clips/app/components/player/timestamped-comment-button.tsx

@@ -0,0 +1,162 @@
+import { useActionMutation, useT } from "@agent-native/core/client";
+import { IconMessagePlus, IconAt, IconMoodSmile } from "@tabler/icons-react";
+import { useEffect, useRef, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+
+import { msToClock } from "./scrubber";
+
+interface TimestampedCommentButtonProps {
+  enableComments: boolean;
+  onOpen: () => void;
+  className?: string;
+}
+
+/** Trigger that opens the docked comment composer, pinned to the current time. */
+export function TimestampedCommentButton({
+  enableComments,
+  onOpen,
+  className,
+}: TimestampedCommentButtonProps) {
+  const t = useT();
+  if (!enableComments) return null;
+  return (
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      className={cn("gap-1.5", className)}
+      onClick={onOpen}
+    >
+      <IconMessagePlus className="h-4 w-4" />
+      {t("commentsPanel.commentButton")}
+    </Button>
+  );
+}
+
+interface TimestampedCommentBarProps {
+  recordingId: string;
+  atMs: number;
+  onClose: () => void;
+  onAdded?: () => void;
+  className?: string;
+}
+
+/**
+ * Bottom-docked comment composer. Render inside a `relative` container (the
+ * video wrapper) so it overlays the bottom of the video at the captured moment.
+ */
+export function TimestampedCommentBar({
+  recordingId,
+  atMs,
+  onClose,
+  onAdded,
+  className,
+}: TimestampedCommentBarProps) {
+  const t = useT();
+  const [draft, setDraft] = useState("");
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  const addComment = useActionMutation("add-comment");
+
+  useEffect(() => {
+    requestAnimationFrame(() => textareaRef.current?.focus());
+  }, []);
+
+  const insertAtCursor = (text: string) => {
+    const el = textareaRef.current;
+    if (!el) {
+      setDraft((d) => d + text);
+      return;
+    }
+    const start = el.selectionStart ?? draft.length;
+    const end = el.selectionEnd ?? draft.length;
+    const next = draft.slice(0, start) + text + draft.slice(end);
+    setDraft(next);
+    requestAnimationFrame(() => {
+      el.focus();
+      const pos = start + text.length;
+      el.setSelectionRange(pos, pos);
+    });
+  };
+
+  const submit = () => {
+    const content = draft.trim();
+    if (!content) return;
+    addComment.mutate(
+      { recordingId, content, videoTimestampMs: atMs },
+      {
+        onSuccess: () => {
+          setDraft("");
+          onAdded?.();
+          onClose();
+        },
+      },
+    );
+  };
+
+  return (
+    <div className={cn("absolute inset-x-0 bottom-0 z-30 p-3", className)}>
+      <div className="rounded-xl border border-border bg-background/95 p-3 shadow-lg backdrop-blur">
+        <Textarea
+          ref={textareaRef}
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+              e.preventDefault();
+              submit();
+            }
+            if (e.key === "Escape") {
+              e.preventDefault();
+              onClose();
+            }
+          }}
+          placeholder={t("commentsPanel.composerPlaceholder")}
+          rows={2}
+          className="min-h-[3rem] resize-none border-0 bg-transparent px-1 text-sm shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
+        />
+        <div className="mt-2 flex items-center justify-between">
+          <div className="flex items-center gap-1">
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8 text-muted-foreground"
+              aria-label={t("commentsPanel.mentionSomeone")}
+              onClick={() => insertAtCursor("@")}
+            >
+              <IconAt className="h-4 w-4" />
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8 text-muted-foreground"
+              aria-label={t("commentsPanel.addEmoji")}
+              onClick={() => insertAtCursor("🙂")}
+            >
+              <IconMoodSmile className="h-4 w-4" />
+            </Button>
+          </div>
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="ghost" size="sm" onClick={onClose}>
+              {t("common.cancel")}
+            </Button>
+            <Button
+              type="button"
+              size="sm"
+              className="rounded-full"
+              disabled={!draft.trim() || addComment.isPending}
+              onClick={submit}
+            >
+              {t("commentsPanel.commentAt")} {msToClock(atMs)}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/corpus/templates/clips/app/i18n/ar-SA.ts

@@ -850,6 +850,10 @@ const messages = {
     replyingTo: "الرد على",
     commentAt: "تعليق عند",
     writeReply: "اكتب ردًا...",
+    commentButton: "تعليق",
+    composerPlaceholder: "أضف تعليقًا…",
+    mentionSomeone: "أذكر شخصًا",
+    addEmoji: "أضف رمزًا تعبيريًا",
   },
   shareMeeting: {
     pageTitle: "ملاحظات الاجتماع · Clips",

package/corpus/templates/clips/app/i18n/de-DE.ts

@@ -878,6 +878,10 @@ Alle sichtbaren Änderungen für Clips-Nutzer werden hier dokumentiert. Du kanns
     replyingTo: "Antwort an",
     commentAt: "Kommentar bei",
     writeReply: "Antwort schreiben...",
+    commentButton: "Kommentar",
+    composerPlaceholder: "Kommentar hinzufügen…",
+    mentionSomeone: "Jemanden erwähnen",
+    addEmoji: "Emoji hinzufügen",
   },
   shareMeeting: {
     pageTitle: "Meeting-Notizen · Clips",

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -849,6 +849,10 @@ All notable user-facing changes to Clips are documented here. Open it any time f
     replyingTo: "Replying to",
     commentAt: "Comment at",
     writeReply: "Write a reply...",
+    commentButton: "Comment",
+    composerPlaceholder: "Add a comment…",
+    mentionSomeone: "Mention someone",
+    addEmoji: "Add emoji",
   },
   shareMeeting: {
     pageTitle: "Meeting notes · Clips",

package/corpus/templates/clips/app/i18n/es-ES.ts

@@ -870,6 +870,10 @@ Todos los cambios visibles para los usuarios de Clips se documentan aquí. Puede
     replyingTo: "Respondiendo a",
     commentAt: "Comentar en",
     writeReply: "Escribe una respuesta...",
+    commentButton: "Comentar",
+    composerPlaceholder: "Añadir un comentario…",
+    mentionSomeone: "Mencionar a alguien",
+    addEmoji: "Añadir emoji",
   },
   shareMeeting: {
     pageTitle: "Notas de reunión · Clips",

package/corpus/templates/clips/app/i18n/fr-FR.ts

@@ -872,6 +872,10 @@ Tous les changements visibles par les utilisateurs de Clips sont documentés ici
     replyingTo: "Réponse à",
     commentAt: "Commentaire à",
     writeReply: "Écrire une réponse...",
+    commentButton: "Commenter",
+    composerPlaceholder: "Ajouter un commentaire…",
+    mentionSomeone: "Mentionner quelqu'un",
+    addEmoji: "Ajouter un emoji",
   },
   shareMeeting: {
     pageTitle: "Notes de réunion · Clips",

package/corpus/templates/clips/app/i18n/hi-IN.ts

@@ -844,6 +844,10 @@ Clips में उपयोगकर्ताओं को दिखने व
     replyingTo: "जवाब दे रहे हैं",
     commentAt: "टिप्पणी करें",
     writeReply: "जवाब लिखें...",
+    commentButton: "टिप्पणी",
+    composerPlaceholder: "टिप्पणी जोड़ें…",
+    mentionSomeone: "किसी का उल्लेख करें",
+    addEmoji: "इमोजी जोड़ें",
   },
   shareMeeting: {
     pageTitle: "मीटिंग नोट्स · Clips",

package/corpus/templates/clips/app/i18n/ja-JP.ts

@@ -860,6 +860,10 @@ Clips のユーザー向けの主な変更はここに記録されます。コ
     replyingTo: "返信先",
     commentAt: "コメント位置",
     writeReply: "返信を書く...",
+    commentButton: "コメント",
+    composerPlaceholder: "コメントを追加…",
+    mentionSomeone: "メンバーをメンション",
+    addEmoji: "絵文字を追加",
   },
   shareMeeting: {
     pageTitle: "会議メモ · Clips",

package/corpus/templates/clips/app/i18n/ko-KR.ts

@@ -851,6 +851,10 @@ Clips의 모든 사용자 대상 변경 사항은 여기에 기록됩니다. 명
     replyingTo: "답글 대상",
     commentAt: "댓글 위치",
     writeReply: "답글 쓰기...",
+    commentButton: "댓글",
+    composerPlaceholder: "댓글 추가…",
+    mentionSomeone: "멘션하기",
+    addEmoji: "이모지 추가",
   },
   shareMeeting: {
     pageTitle: "회의 노트 · Clips",

package/corpus/templates/clips/app/i18n/pt-BR.ts

@@ -867,6 +867,10 @@ Todas as mudanças visíveis para usuários do Clips são documentadas aqui. Voc
     replyingTo: "Respondendo a",
     commentAt: "Comentário em",
     writeReply: "Escreva uma resposta...",
+    commentButton: "Comentar",
+    composerPlaceholder: "Adicionar um comentário…",
+    mentionSomeone: "Mencionar alguém",
+    addEmoji: "Adicionar emoji",
   },
   shareMeeting: {
     pageTitle: "Notas da reunião · Clips",

package/corpus/templates/clips/app/i18n/zh-CN.ts

@@ -817,6 +817,10 @@ Clips 中所有面向用户的重要更改都会记录在这里。你可以随
     replyingTo: "正在回复",
     commentAt: "评论于",
     writeReply: "写回复...",
+    commentButton: "评论",
+    composerPlaceholder: "添加评论…",
+    mentionSomeone: "提及某人",
+    addEmoji: "添加表情",
   },
   shareMeeting: {
     pageTitle: "会议笔记 · Clips",

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

@@ -810,6 +810,10 @@ const messages = {
     replyingTo: "正在回覆",
     commentAt: "評論於",
     writeReply: "寫回覆...",
+    commentButton: "留言",
+    composerPlaceholder: "新增留言…",
+    mentionSomeone: "提及某人",
+    addEmoji: "新增表情符號",
   },
   shareMeeting: {
     pageTitle: "會議筆記 · Clips",

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

@@ -44,6 +44,10 @@ import { InsightsPanel } from "@/components/player/insights-panel";
 import { ReactionsTray } from "@/components/player/reactions-tray";
 import { SettingsPanel } from "@/components/player/settings-panel";
 import { ShareRecordingPopover } from "@/components/player/share-dialog";
+import {
+  TimestampedCommentButton,
+  TimestampedCommentBar,
+} from "@/components/player/timestamped-comment-button";
 import { TranscriptPanel } from "@/components/player/transcript-panel";
 import {
   VideoPlayer,
@@ -210,7 +214,25 @@ export default function RecordingPage() {
   const [theaterMode, setTheaterMode] = useState(false);
   const [editing, setEditing] = useState(false);
   const [currentMs, setCurrentMs] = useState(0);
+  const [commentOpen, setCommentOpen] = useState(false);
+  const [commentAtMs, setCommentAtMs] = useState(0);
   const isCompactLayout = useIsCompactRecordingLayout();
+  // Resolve the playback position for reactions/comments. Native <video> exposes
+  // a live `currentTime`; Loom embeds render in a cross-origin iframe with no
+  // live time bridge, so we fall back to the last position the player reported
+  // via onTimeUpdate (seek/initial start).
+  const resolvePlaybackMs = useCallback(() => {
+    const liveCt = playerRef.current?.video?.currentTime;
+    if (
+      typeof liveCt === "number" &&
+      Number.isFinite(liveCt) &&
+      liveCt >= 0 &&
+      liveCt < 1e7
+    ) {
+      return Math.floor(liveCt * 1000);
+    }
+    return currentMs;
+  }, [currentMs]);
   const transcriptKickedRef = useRef<string | null>(null);
   // When the recording lands in the processing state but never flips to
   // 'ready', stop spinning forever and surface an error banner so the user
@@ -1082,7 +1104,7 @@ export default function RecordingPage() {
             <EditorLayout recordingId={recording.id} className="flex-1" />
           ) : (
             <>
-              <div className="flex-1 min-h-0">
+              <div className="flex-1 min-h-0 relative">
                 <VideoPlayer
                   ref={playerRef}
                   recordingId={recording.id}
@@ -1107,6 +1129,18 @@ export default function RecordingPage() {
                   onTimeUpdate={(ms) => setCurrentMs(ms)}
                   className="h-full"
                 />
+                {commentOpen ? (
+                  <TimestampedCommentBar
+                    recordingId={recording.id}
+                    atMs={commentAtMs}
+                    onClose={() => setCommentOpen(false)}
+                    onAdded={() => {
+                      setPanel("comments");
+                      if (isCompactLayout) setSidePanelOpen(true);
+                      void playerDataQ.refetch();
+                    }}
+                  />
+                ) : null}
               </div>
 
               {/* Title + reactions row */}
@@ -1129,15 +1163,12 @@ export default function RecordingPage() {
                       </span>
                     </NavLink>
                   ) : null}
-                  <EditableRecordingTitle
-                    recordingId={recording.id}
-                    title={recording.title}
-                    canEdit={canEdit}
-                    displayTitle={visibleTitle}
-                    showPendingSkeleton={showTitleSkeleton}
-                    className="text-base font-semibold"
-                    inputClassName="h-8 text-base font-semibold"
-                    skeletonClassName="h-5 w-72 max-w-full"
+                  <TimestampedCommentButton
+                    enableComments={recording.enableComments}
+                    onOpen={() => {
+                      setCommentAtMs(resolvePlaybackMs());
+                      setCommentOpen(true);
+                    }}
                   />
                   {recording.description ? (
                     <p className="text-sm text-muted-foreground line-clamp-2">
@@ -1150,14 +1181,7 @@ export default function RecordingPage() {
                     disabled={!recording.enableReactions}
                     onReact={(emoji) => {
                       tracking.reportReaction(emoji);
-                      const liveCt = playerRef.current?.video?.currentTime;
-                      const liveMs =
-                        typeof liveCt === "number" &&
-                        Number.isFinite(liveCt) &&
-                        liveCt >= 0 &&
-                        liveCt < 1e7
-                          ? Math.floor(liveCt * 1000)
-                          : currentMs;
+                      const liveMs = resolvePlaybackMs();
                       fetch(
                         agentNativePath(
                           "/_agent-native/actions/react-to-recording",

package/corpus/templates/plan/.agents/skills/visual-plan/references/local-files.md

@@ -35,8 +35,10 @@ The local-files contract:
   `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
   — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
   (a static template literal is accepted only when it has no `${...}`
-  interpolation). `plan local check` validates these required fields against the
-  renderer schema.
+  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green `check` does not guarantee the plan renders;
+  `plan local verify` is the authoritative validation against the real renderer
+  schema.
 - **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
   repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
   or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
@@ -61,9 +63,16 @@ The local-files contract:
   running local Plan app.
 - **Headless verify.** Run
   `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the
-  `bridgeUrl` from the verify/serve JSON to read the concrete validation error.
+  It starts the bridge, checks the private-network preflight and JSON payload, AND
+  validates the content against the real renderer schema via the Plan app's
+  `validate-local-plan-source` action. A non-`ok` result with
+  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
+  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
+  is `false`, the Plan app did not expose the validate endpoint (older/unreachable
+  deploy) — point `--app-url` at a current Plan app (e.g. a local
+  `http://localhost:8096`) for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
+  concrete validation error.
 - **Never call hosted tools for that plan/recap.** Do not call
   `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
   `create-plan-design`, `create-visual-recap`, `create-visual-questions`,

package/corpus/templates/plan/.agents/skills/visual-recap/references/local-files.md

@@ -35,8 +35,10 @@ The local-files contract:
   `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
   — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
   (a static template literal is accepted only when it has no `${...}`
-  interpolation). `plan local check` validates these required fields against the
-  renderer schema.
+  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green `check` does not guarantee the plan renders;
+  `plan local verify` is the authoritative validation against the real renderer
+  schema.
 - **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
   repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
   or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
@@ -61,9 +63,16 @@ The local-files contract:
   running local Plan app.
 - **Headless verify.** Run
   `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the
-  `bridgeUrl` from the verify/serve JSON to read the concrete validation error.
+  It starts the bridge, checks the private-network preflight and JSON payload, AND
+  validates the content against the real renderer schema via the Plan app's
+  `validate-local-plan-source` action. A non-`ok` result with
+  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
+  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
+  is `false`, the Plan app did not expose the validate endpoint (older/unreachable
+  deploy) — point `--app-url` at a current Plan app (e.g. a local
+  `http://localhost:8096`) for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
+  concrete validation error.
 - **Never call hosted tools for that plan/recap.** Do not call
   `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
   `create-plan-design`, `create-visual-recap`, `create-visual-questions`,