@agent-native/core 0.97.0 → 0.98.0

package/corpus/templates/plan/actions/create-plan-design.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 designSurfaceSchema = z.enum([
   "desktop",
@@ -100,89 +103,94 @@ const designContextRecordSchema = z.record(z.string(), z.unknown()).refine(
   { message: "Design context metadata is too large." },
 );
 
+const CONTENT_DESCRIPTION =
+  "Full structured content when the caller has already authored the design/prototype. Prefer screens/transitions for normal /plan-design creation.";
+
+// 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 createPlanDesignSchema = z.object({
+  title: z.string().optional().describe("Short design plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the design direction, shown as the lede under the title. Keep it to a single tight line.",
+    ),
+  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 design review focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  screens: z
+    .array(designScreenSchema)
+    .max(6)
+    .optional()
+    .default([])
+    .describe(
+      "Full-fidelity design screens. Include one to six substantial screens/states with real labels, brand styling, and data-design-id attributes on editable elements. Use CSS for Tailwind-like utility classes because the Plan renderer does not load arbitrary CDN scripts.",
+    ),
+  transitions: z
+    .array(designTransitionSchema)
+    .max(24)
+    .optional()
+    .default([])
+    .describe(
+      "Expected screen transitions for the Prototype tab. Use data-goto attributes in screen HTML for true route/step changes.",
+    ),
+  designMd: z
+    .string()
+    .max(100_000)
+    .optional()
+    .describe("Optional design.md content used as design direction"),
+  brandKit: designContextRecordSchema
+    .optional()
+    .describe("Optional parsed brand kit or .fig design-system data"),
+  codebaseStyles: designContextRecordSchema
+    .optional()
+    .describe("Optional parsed CSS vars, Tailwind tokens, fonts, and colors"),
+  designNotes: z
+    .string()
+    .max(20_000)
+    .optional()
+    .describe("Concise notes about brand/style assumptions"),
+  implementationNotes: z
+    .string()
+    .max(20_000)
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  markdown: z
+    .string()
+    .max(100_000)
+    .optional()
+    .describe("Markdown/text fallback or source design plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional legacy plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a full-fidelity branded design plan with a Design tab (editable design canvas) and optional Prototype tab. For a document-first plan use create-visual-plan; for a wireframe-canvas plan use create-ui-plan; for a recap of an existing diff use create-visual-recap; for a functional prototype use create-prototype-plan. Use design.md, .fig brand kits, and codebase CSS/Tailwind/token evidence when available. Design screens are bounded HTML/CSS fragments with data-design-id targets. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short design plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the design direction, shown as the lede under the title. Keep it to a single tight line.",
-        ),
-      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 design review focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          "Full structured content when the caller has already authored the design/prototype. Prefer screens/transitions for normal /plan-design creation.",
-        ),
-      screens: z
-        .array(designScreenSchema)
-        .max(6)
-        .optional()
-        .default([])
-        .describe(
-          "Full-fidelity design screens. Include one to six substantial screens/states with real labels, brand styling, and data-design-id attributes on editable elements. Use CSS for Tailwind-like utility classes because the Plan renderer does not load arbitrary CDN scripts.",
-        ),
-      transitions: z
-        .array(designTransitionSchema)
-        .max(24)
-        .optional()
-        .default([])
-        .describe(
-          "Expected screen transitions for the Prototype tab. Use data-goto attributes in screen HTML for true route/step changes.",
-        ),
-      designMd: z
-        .string()
-        .max(100_000)
-        .optional()
-        .describe("Optional design.md content used as design direction"),
-      brandKit: designContextRecordSchema
-        .optional()
-        .describe("Optional parsed brand kit or .fig design-system data"),
-      codebaseStyles: designContextRecordSchema
-        .optional()
-        .describe(
-          "Optional parsed CSS vars, Tailwind tokens, fonts, and colors",
-        ),
-      designNotes: z
-        .string()
-        .max(20_000)
-        .optional()
-        .describe("Concise notes about brand/style assumptions"),
-      implementationNotes: z
-        .string()
-        .max(20_000)
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      markdown: z
-        .string()
-        .max(100_000)
-        .optional()
-        .describe("Markdown/text fallback or source design plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional legacy plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
-      message: "Either brief or goal is required.",
-    }),
+  schema: createPlanDesignSchema.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: createPlanDesignSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

package/corpus/templates/plan/actions/create-prototype-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 prototypeSurfaceSchema = z.enum([
   "desktop",
@@ -80,67 +83,77 @@ const prototypeTransitionSchema = z.object({
   trigger: z.string().optional(),
 });
 
+const CONTENT_DESCRIPTION =
+  "Full structured content when the caller has already authored a prototype. Prefer screens/transitions unless replacing the whole document.";
+
+// 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 createPrototypePlanSchema = z.object({
+  title: z.string().optional().describe("Short visual plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "The question the prototype answers, in one short line. Shown as the lede under the title — keep it tight, not a paragraph.",
+    ),
+  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 prototype review focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  screens: z
+    .array(prototypeScreenSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Prototype screens. Default to one functional screen when local UI behavior is enough; use 2-4 screens only for true routes/steps. Screen HTML should include working local controls, inputs, toggles, lists, filters, or lightweight flows where relevant.",
+    ),
+  transitions: z
+    .array(prototypeTransitionSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Expected screen/route transitions. The viewer also honors data-goto attributes in screen HTML, but ordinary UI state should stay inside the functional prototype.",
+    ),
+  implementationNotes: z
+    .string()
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source visual plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional legacy plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a plan whose primary review surface is a running interactive prototype. For a document-first plan use create-visual-plan; for a UI-first wireframe canvas use create-ui-plan; for a recap of an existing diff use create-visual-recap; for full-fidelity branded design use create-plan-design. Prototype screen HTML uses safe Alpine-like directives for local state and data-goto for screen navigation only. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short visual plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "The question the prototype answers, in one short line. Shown as the lede under the title — keep it tight, not a paragraph.",
-        ),
-      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 prototype review focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          "Full structured content when the caller has already authored a prototype. Prefer screens/transitions unless replacing the whole document.",
-        ),
-      screens: z
-        .array(prototypeScreenSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Prototype screens. Default to one functional screen when local UI behavior is enough; use 2-4 screens only for true routes/steps. Screen HTML should include working local controls, inputs, toggles, lists, filters, or lightweight flows where relevant.",
-        ),
-      transitions: z
-        .array(prototypeTransitionSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Expected screen/route transitions. The viewer also honors data-goto attributes in screen HTML, but ordinary UI state should stay inside the functional prototype.",
-        ),
-      implementationNotes: z
-        .string()
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source visual plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional legacy plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
-      message: "Either brief or goal is required.",
-    }),
+  schema: createPrototypePlanSchema.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: createPrototypePlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

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,