@agent-native/core 0.96.0 → 0.98.0

package/corpus/templates/plan/actions/create-ui-plan.ts

@@ -34,7 +34,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 const uiPlanStateSchema = z.object({
   name: z.string().min(1).describe("State or screen name"),
@@ -52,64 +55,76 @@ const uiPlanComponentSchema = z.object({
     .describe("Intent, constraints, and details for this UI part"),
 });
 
+const CONTENT_DESCRIPTION =
+  'Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe\'s data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Call get-plan-blocks first for visual frame guidance before choosing frame: "show" or frame: "hide". Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.';
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal requirement) only applies to the real runtime
+// `schema` further down.
+const createUiPlanSchema = z.object({
+  title: z.string().optional().describe("Short UI plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the UI plan, shown as the lede under the title. Keep it to a single tight line; the document carries the detail.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  source: planSourceSchema.optional().default("manual"),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z.string().optional().describe("Current UI plan focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source UI plan"),
+  states: z
+    .array(uiPlanStateSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Screens or states to show primarily on the optional top pan/zoom canvas, such as Default, Empty, Loading, Error, Mobile, or Agent handoff. For component/widget work, prefer focused component variants and one real product-context frame over fake desktop/mobile journeys. Omit when visual states would not help.",
+    ),
+  components: z
+    .array(uiPlanComponentSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Focused UI parts and constraints for canvas annotations and the implementation document. Do not use these to create redundant wireframe tabs when the top canvas already shows the UI.",
+    ),
+  implementationNotes: z
+    .string()
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional additional plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a UI-first plan whose centerpiece is wireframed screens/states on a canvas. For a document-first plan use create-visual-plan; for a recap of an existing diff use create-visual-recap; for a running interactive prototype use create-prototype-plan; for a full-fidelity branded design use create-plan-design. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short UI plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the UI plan, shown as the lede under the title. Keep it to a single tight line; the document carries the detail.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      source: planSourceSchema.optional().default("manual"),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z.string().optional().describe("Current UI plan focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          'Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe\'s data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Call get-plan-blocks first for visual frame guidance before choosing frame: "show" or frame: "hide". Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.',
-        ),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source UI plan"),
-      states: z
-        .array(uiPlanStateSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Screens or states to show primarily on the optional top pan/zoom canvas, such as Default, Empty, Loading, Error, Mobile, or Agent handoff. For component/widget work, prefer focused component variants and one real product-context frame over fake desktop/mobile journeys. Omit when visual states would not help.",
-        ),
-      components: z
-        .array(uiPlanComponentSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Focused UI parts and constraints for canvas annotations and the implementation document. Do not use these to create redundant wireframe tabs when the top canvas already shows the UI.",
-        ),
-      implementationNotes: z
-        .string()
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional additional plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
+  schema: createUiPlanSchema.refine(
+    (args) => Boolean(args.brief || args.goal),
+    {
       message: "Either brief or goal is required.",
-    }),
+    },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: createUiPlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

package/corpus/templates/plan/actions/create-visual-plan.ts

@@ -36,7 +36,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 function inferImportedPlanTitle(planText: string): string {
   const firstHeading = planText
@@ -51,59 +54,70 @@ function inferImportedPlanTitle(planText: string): string {
   return firstLine ? firstLine.slice(0, 90) : "Imported visual plan";
 }
 
+const CONTENT_DESCRIPTION =
+  "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.";
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal/planText requirement) is applied only to the real
+// runtime `schema` further down — refine predicates aren't serializable JSON
+// Schema anyway, so the advertised copy never needs it.
+const createVisualPlanSchema = z.object({
+  title: z.string().optional().describe("Short plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the plan, shown as the lede under the title. Keep it to a single tight line — the document body carries the detail, not this summary.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  planText: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Existing Codex, Claude Code, Markdown, or pasted plan text to preserve and turn into a visual review plan.",
+    ),
+  source: planSourceSchema.optional(),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z.string().optional().describe("Current plan focus"),
+  status: planStatusSchema.optional().default("review"),
+  html: z
+    .string()
+    .optional()
+    .describe(
+      "Legacy: a standalone HTML document. Setting this NULLS structured content — blocks, contentPatches, inline editing, and MDX round-trip all stop working for this plan. Only for preserving a pre-existing HTML artifact; never author new plans this way.",
+    ),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Readable plan sections and visual blocks"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a document-first structured plan for any coding task. Call this EXACTLY ONCE per plan — produce the final plan in a single call. Do NOT create a draft and then a second 'clean' version; if you need to revise after creating, call update-visual-plan with the existing planId instead of creating another plan (each create renders its own embed, so a second create leaves a duplicate). For a plan whose centerpiece is wireframed screens/states on a canvas use create-ui-plan; for a recap of an existing diff use create-visual-recap; for a running interactive prototype use create-prototype-plan; for a full-fidelity branded design use create-plan-design. Also accepts imported Codex, Claude Code, Markdown, or pasted plan text via planText. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the plan, shown as the lede under the title. Keep it to a single tight line — the document body carries the detail, not this summary.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      planText: z
-        .string()
-        .min(1)
-        .optional()
-        .describe(
-          "Existing Codex, Claude Code, Markdown, or pasted plan text to preserve and turn into a visual review plan.",
-        ),
-      source: planSourceSchema.optional(),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z.string().optional().describe("Current plan focus"),
-      status: planStatusSchema.optional().default("review"),
-      html: z
-        .string()
-        .optional()
-        .describe(
-          "Legacy: a standalone HTML document. Setting this NULLS structured content — blocks, contentPatches, inline editing, and MDX round-trip all stop working for this plan. Only for preserving a pre-existing HTML artifact; never author new plans this way.",
-        ),
-      content: planContentSchema
-        .optional()
-        .describe(
-          "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.",
-        ),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Readable plan sections and visual blocks"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal || args.planText), {
-      message: "Either brief, goal, or planText is required.",
-    }),
+  schema: createVisualPlanSchema.refine(
+    (args) => Boolean(args.brief || args.goal || args.planText),
+    { message: "Either brief, goal, or planText is required." },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: createVisualPlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

package/corpus/templates/plan/actions/restore-plan-version.ts

@@ -38,6 +38,13 @@ export default defineAction({
   run: async ({ planId, versionId }) => {
     const access = await assertPlanEditor(planId);
     const ownerEmail = access.resource.ownerEmail as string;
+    // Optimistic-concurrency fence, mirroring the versionAtLoad/updatedAt
+    // pattern in update-visual-plan.ts: captured before any restore work
+    // starts, then used to guard the leading `plans` UPDATE below so a
+    // restore racing a concurrent edit fails cleanly instead of silently
+    // clobbering it or interleaving writes.
+    const versionAtLoad = (access.resource as typeof schema.plans.$inferSelect)
+      .updatedAt;
     const db = getDb();
 
     const [version] = await db
@@ -63,114 +70,137 @@ export default defineAction({
     const snapshot = parsePlanVersionSnapshot(version.snapshotJson);
     const now = nowIso();
 
-    await db
-      .update(schema.plans)
-      .set({
-        title: snapshot.plan.title,
-        brief: snapshot.plan.brief,
-        status: snapshot.plan.status,
-        source: snapshot.plan.source,
-        repoPath: snapshot.plan.repoPath ?? null,
-        currentFocus: snapshot.plan.currentFocus ?? null,
-        html: snapshot.plan.html ?? null,
-        markdown: snapshot.plan.markdown ?? null,
-        content: snapshot.plan.content
-          ? serializePlanContent(snapshot.plan.content)
-          : null,
-        approvedAt: snapshot.plan.approvedAt ?? null,
-        updatedAt: now,
-      })
-      .where(eq(schema.plans.id, planId));
-
-    // Preserve comment anchors for sections whose ids survive in the snapshot.
-    // Strategy: capture comment→sectionId pairs for surviving sections first,
-    // then null ALL sectionIds (required to satisfy FK before section deletion),
-    // delete and re-insert sections, then re-anchor the surviving comments.
-    const survivingSectionIds = new Set(snapshot.sections.map((s) => s.id));
-    const commentAnchorMap = new Map<string, string>(); // commentId → sectionId
-    if (survivingSectionIds.size > 0) {
-      const anchored = await db
-        .select({
-          id: schema.planComments.id,
-          sectionId: schema.planComments.sectionId,
+    // The destructive part of the restore (plans update, comment sectionId
+    // nulling, section delete/re-insert, comment re-anchor, and the restore
+    // event) runs as a single atomic transaction. Without this, a
+    // mid-sequence failure could leave the plan with zero sections and
+    // permanently detached comments. better-sqlite3's normally-sync-only
+    // transaction() is patched to support async callbacks in
+    // packages/core/src/db/create-get-db.ts (patchBetterSqliteTransactions,
+    // wired into createGetDb for local sqlite urls), so this is safe on the
+    // local driver as well as libsql/Postgres.
+    await db.transaction(async (tx) => {
+      const updatedRows = await tx
+        .update(schema.plans)
+        .set({
+          title: snapshot.plan.title,
+          brief: snapshot.plan.brief,
+          status: snapshot.plan.status,
+          source: snapshot.plan.source,
+          repoPath: snapshot.plan.repoPath ?? null,
+          currentFocus: snapshot.plan.currentFocus ?? null,
+          html: snapshot.plan.html ?? null,
+          markdown: snapshot.plan.markdown ?? null,
+          content: snapshot.plan.content
+            ? serializePlanContent(snapshot.plan.content)
+            : null,
+          approvedAt: snapshot.plan.approvedAt ?? null,
+          updatedAt: now,
         })
-        .from(schema.planComments)
         .where(
           and(
-            eq(schema.planComments.planId, planId),
-            inArray(
-              schema.planComments.sectionId,
-              Array.from(survivingSectionIds),
-            ),
+            eq(schema.plans.id, planId),
+            eq(schema.plans.updatedAt, versionAtLoad),
           ),
+        )
+        .returning({ id: schema.plans.id });
+
+      if (updatedRows.length === 0) {
+        throw new Error(
+          "This plan was updated by someone else while the restore was being prepared. Reload the plan and try restoring again.",
         );
-      for (const row of anchored) {
-        if (row.sectionId) commentAnchorMap.set(row.id, row.sectionId);
       }
-    }
-
-    // Null ALL comment anchors so the section delete below doesn't violate FK.
-    await db
-      .update(schema.planComments)
-      .set({ sectionId: null, updatedAt: now })
-      .where(eq(schema.planComments.planId, planId));
-
-    await db
-      .delete(schema.planSections)
-      .where(eq(schema.planSections.planId, planId));
-
-    if (snapshot.sections.length > 0) {
-      await db.insert(schema.planSections).values(
-        snapshot.sections.map((section, index) => ({
-          id: section.id,
-          planId,
-          type: section.type,
-          title: section.title,
-          body: section.body,
-          html: section.html ?? null,
-          order: section.order ?? index,
-          createdBy: section.createdBy,
-          createdAt: section.createdAt || now,
-          updatedAt: section.updatedAt || now,
-        })),
-      );
-    }
-
-    // Re-anchor comments that were pointing to sections present in the snapshot.
-    // These sections now exist again, so the FK is satisfied and the comment
-    // threads remain navigable. Comments on sections that did not survive stay
-    // detached (sectionId = null).
-    if (commentAnchorMap.size > 0) {
-      const anchorGroups = new Map<string, string[]>(); // sectionId → commentIds
-      for (const [commentId, sectionId] of commentAnchorMap) {
-        const ids = anchorGroups.get(sectionId) ?? [];
-        ids.push(commentId);
-        anchorGroups.set(sectionId, ids);
-      }
-      for (const [sectionId, commentIds] of anchorGroups) {
-        await db
-          .update(schema.planComments)
-          .set({ sectionId, updatedAt: now })
+
+      // Preserve comment anchors for sections whose ids survive in the snapshot.
+      // Strategy: capture comment→sectionId pairs for surviving sections first,
+      // then null ALL sectionIds (required to satisfy FK before section deletion),
+      // delete and re-insert sections, then re-anchor the surviving comments.
+      const survivingSectionIds = new Set(snapshot.sections.map((s) => s.id));
+      const commentAnchorMap = new Map<string, string>(); // commentId → sectionId
+      if (survivingSectionIds.size > 0) {
+        const anchored = await tx
+          .select({
+            id: schema.planComments.id,
+            sectionId: schema.planComments.sectionId,
+          })
+          .from(schema.planComments)
           .where(
             and(
               eq(schema.planComments.planId, planId),
-              inArray(schema.planComments.id, commentIds),
+              inArray(
+                schema.planComments.sectionId,
+                Array.from(survivingSectionIds),
+              ),
             ),
           );
+        for (const row of anchored) {
+          if (row.sectionId) commentAnchorMap.set(row.id, row.sectionId);
+        }
       }
-    }
-
-    await db.insert(schema.planEvents).values({
-      id: newId("evt"),
-      planId,
-      type: "plan.version.restored",
-      message: "Restored plan from version history.",
-      payload: JSON.stringify({
-        restoredVersionId: version.id,
-        restoredVersionCreatedAt: version.createdAt,
-      }),
-      createdBy: "agent",
-      createdAt: now,
+
+      // Null ALL comment anchors so the section delete below doesn't violate FK.
+      await tx
+        .update(schema.planComments)
+        .set({ sectionId: null, updatedAt: now })
+        .where(eq(schema.planComments.planId, planId));
+
+      await tx
+        .delete(schema.planSections)
+        .where(eq(schema.planSections.planId, planId));
+
+      if (snapshot.sections.length > 0) {
+        await tx.insert(schema.planSections).values(
+          snapshot.sections.map((section, index) => ({
+            id: section.id,
+            planId,
+            type: section.type,
+            title: section.title,
+            body: section.body,
+            html: section.html ?? null,
+            order: section.order ?? index,
+            createdBy: section.createdBy,
+            createdAt: section.createdAt || now,
+            updatedAt: section.updatedAt || now,
+          })),
+        );
+      }
+
+      // Re-anchor comments that were pointing to sections present in the snapshot.
+      // These sections now exist again, so the FK is satisfied and the comment
+      // threads remain navigable. Comments on sections that did not survive stay
+      // detached (sectionId = null).
+      if (commentAnchorMap.size > 0) {
+        const anchorGroups = new Map<string, string[]>(); // sectionId → commentIds
+        for (const [commentId, sectionId] of commentAnchorMap) {
+          const ids = anchorGroups.get(sectionId) ?? [];
+          ids.push(commentId);
+          anchorGroups.set(sectionId, ids);
+        }
+        for (const [sectionId, commentIds] of anchorGroups) {
+          await tx
+            .update(schema.planComments)
+            .set({ sectionId, updatedAt: now })
+            .where(
+              and(
+                eq(schema.planComments.planId, planId),
+                inArray(schema.planComments.id, commentIds),
+              ),
+            );
+        }
+      }
+
+      await tx.insert(schema.planEvents).values({
+        id: newId("evt"),
+        planId,
+        type: "plan.version.restored",
+        message: "Restored plan from version history.",
+        payload: JSON.stringify({
+          restoredVersionId: version.id,
+          restoredVersionCreatedAt: version.createdAt,
+        }),
+        createdBy: "agent",
+        createdAt: now,
+      });
     });
 
     const bundle = await loadPlanBundle(planId);

package/corpus/templates/plan/actions/update-local-plan-folder.ts

@@ -15,6 +15,8 @@ import {
 import { normalizePlanContent } from "../server/plan-content.js";
 import { referencedBlockIdsForPlanComments } from "../server/plan-mdx.js";
 import {
+  agentPlanContentPatchesSchema,
+  agentPlanContentSchema,
   applyPlanContentPatches,
   planContentPatchesSchema,
   planContentSchema,
@@ -22,41 +24,52 @@ import {
 } from "../shared/plan-content.js";
 import type { PlanKind } from "../shared/types.js";
 
+const CONTENT_DESCRIPTION =
+  "Full structured content replacement. Prefer contentPatches for targeted edits.";
+const CONTENT_PATCHES_DESCRIPTION =
+  "Targeted structured content edits addressed by stable block/prototype/canvas ids.";
+
+// Named so `agentInputSchema` below can `.extend()` it with compact
+// `content`/`contentPatches` fields instead of duplicating every other key.
+const updateLocalPlanFolderSchema = z.object({
+  slug: z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9._-]+$/)
+    .describe("Folder name under PLAN_LOCAL_DIR, for example checkout-review."),
+  path: z
+    .string()
+    .optional()
+    .describe(
+      "Optional repo-relative folder path, for example plans/checkout-review.",
+    ),
+  title: z.string().optional().describe("Plan title."),
+  brief: z
+    .string()
+    .optional()
+    .describe("One-line plan summary shown under the title."),
+  kind: localPlanKindSchema.optional(),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  contentPatches: planContentPatchesSchema
+    .optional()
+    .default([])
+    .describe(CONTENT_PATCHES_DESCRIPTION),
+  note: z.string().optional().describe("Short audit note for callers."),
+});
+
 export default defineAction({
   description:
     "Update a DB-free local Agent-Native Plan MDX folder from PLAN_LOCAL_DIR or an optional repo-relative path. Applies the same structured contentPatches used by update-visual-plan, writes plan.mdx/canvas.mdx/prototype.mdx back to the same local folder, and never writes to the database.",
-  schema: z.object({
-    slug: z
-      .string()
-      .min(1)
-      .regex(/^[A-Za-z0-9._-]+$/)
-      .describe(
-        "Folder name under PLAN_LOCAL_DIR, for example checkout-review.",
-      ),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Optional repo-relative folder path, for example plans/checkout-review.",
-      ),
-    title: z.string().optional().describe("Plan title."),
-    brief: z
-      .string()
-      .optional()
-      .describe("One-line plan summary shown under the title."),
-    kind: localPlanKindSchema.optional(),
-    content: planContentSchema
-      .optional()
-      .describe(
-        "Full structured content replacement. Prefer contentPatches for targeted edits.",
-      ),
-    contentPatches: planContentPatchesSchema
+  schema: updateLocalPlanFolderSchema,
+  // ADVERTISED-ONLY: same shape, but `content`/`contentPatches` swap the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: updateLocalPlanFolderSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+    contentPatches: agentPlanContentPatchesSchema
       .optional()
       .default([])
-      .describe(
-        "Targeted structured content edits addressed by stable block/prototype/canvas ids.",
-      ),
-    note: z.string().optional().describe("Short audit note for callers."),
+      .describe(CONTENT_PATCHES_DESCRIPTION),
   }),
   requiresAuth: false,
   publicAgent: {