@agent-native/core 0.136.4 → 0.137.0

package/corpus/templates/factory/server/triage/sentry-client.ts

@@ -0,0 +1,180 @@
+import { resolveConnectorSecret } from "../connectors/credentials.js";
+
+const DEFAULT_BASE_URL = "https://sentry.io/api/0";
+const MAX_LIMIT = 100;
+
+export interface SentryClientOptions {
+  ownerEmail: string;
+  orgId?: string | null;
+  orgSlug?: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export interface SentryIssue {
+  id: string;
+  shortId: string;
+  title: string;
+  culprit: string;
+  permalink: string;
+  level: string;
+  status: string;
+  projectSlug: string;
+  count: string;
+  firstSeen: string;
+  lastSeen: string;
+}
+
+export interface SentryEvent {
+  eventId: string;
+  title: string;
+  message: string;
+  dateCreated: string;
+  tags: readonly { key: string; value: string }[];
+  context: Readonly<Record<string, unknown>>;
+}
+
+interface JsonResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Sentry response was not an object");
+  return value as Record<string, unknown>;
+}
+
+function string(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0)
+    throw new Error(`Sentry response is missing ${field}`);
+  return value;
+}
+
+function limit(value?: number): number {
+  if (value === undefined) return MAX_LIMIT;
+  if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT)
+    throw new Error(`Sentry limit must be an integer from 1 to ${MAX_LIMIT}`);
+  return value;
+}
+
+function parseIssue(value: unknown): SentryIssue {
+  const item = object(value);
+  const project = object(item.project);
+  return {
+    id: string(item.id, "issue id"),
+    shortId: string(item.shortId, "issue short id"),
+    title: string(item.title, "issue title"),
+    culprit: string(item.culprit, "issue culprit"),
+    permalink: string(item.permalink, "issue permalink"),
+    level: string(item.level, "issue level"),
+    status: string(item.status, "issue status"),
+    projectSlug: string(project.slug, "issue project slug"),
+    count: string(item.count, "issue count"),
+    firstSeen: string(item.firstSeen, "issue first seen"),
+    lastSeen: string(item.lastSeen, "issue last seen"),
+  };
+}
+
+function parseEvent(value: unknown): SentryEvent {
+  const item = object(value);
+  const tags = item.tags;
+  if (!Array.isArray(tags))
+    throw new Error("Sentry event response is missing tags");
+  return {
+    eventId: string(item.eventID, "event id"),
+    title: string(item.title, "event title"),
+    message: string(item.message, "event message"),
+    dateCreated: string(item.dateCreated, "event created time"),
+    tags: tags.map((tag) => {
+      const value = object(tag);
+      return {
+        key: string(value.key, "event tag key"),
+        value: string(value.value, "event tag value"),
+      };
+    }),
+    context: object(item.context),
+  };
+}
+
+export function createSentryClient(options: SentryClientOptions) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+
+  async function credential(
+    key: "SENTRY_SERVER_TOKEN" | "SENTRY_AUTH_TOKEN",
+  ): Promise<string | undefined> {
+    return resolveConnectorSecret(key, options.ownerEmail, {
+      orgId: options.orgId,
+    });
+  }
+
+  async function request<T>(path: string): Promise<T> {
+    const token =
+      (await credential("SENTRY_SERVER_TOKEN")) ??
+      (await credential("SENTRY_AUTH_TOKEN"));
+    if (!token)
+      throw new Error(
+        "SENTRY_SERVER_TOKEN or SENTRY_AUTH_TOKEN is not configured for this workspace",
+      );
+    const response = (await fetchImpl(`${baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })) as JsonResponse;
+    if (!response.ok) {
+      const detail = (await response.text()).slice(0, 500);
+      throw new Error(
+        `Sentry API request failed: HTTP ${response.status}${detail ? ` - ${detail}` : ""}`,
+      );
+    }
+    return (await response.json()) as T;
+  }
+
+  async function organization(): Promise<string> {
+    const value =
+      options.orgSlug?.trim() ||
+      (await resolveConnectorSecret("SENTRY_ORG_SLUG", options.ownerEmail, {
+        orgId: options.orgId,
+      }));
+    if (!value)
+      throw new Error("SENTRY_ORG_SLUG is not configured for this workspace");
+    return encodeURIComponent(value);
+  }
+
+  return {
+    async listIssues(
+      query?: string,
+      requestedLimit?: number,
+    ): Promise<readonly SentryIssue[]> {
+      const params = new URLSearchParams({
+        limit: String(limit(requestedLimit)),
+        sort: "freq",
+      });
+      if (query?.trim()) params.set("query", query.trim().slice(0, 500));
+      const value = await request<unknown>(
+        `/organizations/${await organization()}/issues/?${params}`,
+      );
+      if (!Array.isArray(value))
+        throw new Error("Sentry issue response was not an array");
+      return value.map(parseIssue);
+    },
+
+    async listEvents(
+      issueId: string,
+      requestedLimit?: number,
+    ): Promise<readonly SentryEvent[]> {
+      const id = issueId.trim();
+      if (!id) throw new Error("Sentry issue id is required");
+      const params = new URLSearchParams({
+        limit: String(limit(requestedLimit)),
+      });
+      const value = await request<unknown>(
+        `/organizations/${await organization()}/issues/${encodeURIComponent(id)}/events/?${params}`,
+      );
+      if (!Array.isArray(value))
+        throw new Error("Sentry event response was not an array");
+      return value.map(parseEvent);
+    },
+  };
+}

package/corpus/templates/factory/server/triage/slack-client.ts

@@ -1,10 +1,16 @@
 import { resolveConnectorSecret } from "../connectors/credentials.js";
 import {
   getChannelHistory as readChannelHistory,
+  addEyesReaction as writeEyesReaction,
+  getThread as readThread,
   getTeamInfo as readTeamInfo,
+  postThreadReply as writeThreadReply,
   type ChannelHistoryResult,
+  type SlackPostMessageResult,
+  type SlackReactionResult,
   type SlackTeamInfo,
   type SlackTokenResolver,
+  type ThreadRepliesResult,
   type Workspace,
 } from "../connectors/slack.js";
 
@@ -51,5 +57,42 @@ export function createSlackReader(identity: SlackReaderIdentity) {
     getTeamInfo(workspace: Workspace): Promise<SlackTeamInfo> {
       return readTeamInfo(workspace, tokenResolver);
     },
+    getThread(
+      workspace: Workspace,
+      channelId: string,
+      threadTs: string,
+      limit?: number,
+      cursor?: string,
+    ): Promise<ThreadRepliesResult> {
+      return readThread(
+        workspace,
+        channelId,
+        threadTs,
+        limit,
+        cursor,
+        tokenResolver,
+      );
+    },
+    addEyesReaction(
+      workspace: Workspace,
+      channelId: string,
+      timestamp: string,
+    ): Promise<SlackReactionResult> {
+      return writeEyesReaction(workspace, channelId, timestamp, tokenResolver);
+    },
+    postThreadReply(
+      workspace: Workspace,
+      channelId: string,
+      threadTs: string,
+      text: string,
+    ): Promise<SlackPostMessageResult> {
+      return writeThreadReply(
+        workspace,
+        channelId,
+        threadTs,
+        text,
+        tokenResolver,
+      );
+    },
   };
 }

package/corpus/templates/factory/server/triage/slack-poller.ts

@@ -60,7 +60,7 @@ function toEnvelope(
 
   return {
     source: "slack",
-    externalId: `${channelId}:${message.ts}`,
+    externalId: `${channelId}:${threadTs}`,
     receivedAt: new Date().toISOString(),
     ...(sourceUrl ? { sourceUrl } : {}),
     title: messageLabel(message),
@@ -133,6 +133,13 @@ export async function pollSlackChannel({
     .map((message) => ({ message, ts: numericTs(message.ts) }))
     .filter(({ ts }) => ts > priorTs)
     .sort((a, b) => a.ts - b.ts);
+  const seenThreads = new Set<string>();
+  const uniqueNewMessages = newMessages.filter(({ message }) => {
+    const threadTs = message.thread_ts ?? message.ts;
+    if (seenThreads.has(threadTs)) return false;
+    seenThreads.add(threadTs);
+    return true;
+  });
   const maxSeen = messages.reduce(
     (max, message) => {
       const ts = numericTs(message.ts);
@@ -142,7 +149,7 @@ export async function pollSlackChannel({
   );
 
   return {
-    envelopes: newMessages.map(({ message }) =>
+    envelopes: uniqueNewMessages.map(({ message }) =>
       toEnvelope(channelId, message, teamDomain),
     ),
     nextLastSlackTs: maxSeen.raw,

package/corpus/templates/plan/.agents/skills/visual-plan/SKILL.md

@@ -292,6 +292,11 @@ folding framework chrome into the product UI.
   `content.prototype`, and rely on the top visual tabs to switch between them.
   When both surfaces are present, open the Wireframes tab by default; the
   prototype remains available as the interactive follow-up view.
+- **Default to wireframes.** A clean, minimal UI, a high UX bar, or references
+  to Linear/Vercel describe the content and density bar; they do not request
+  full-fidelity design mode. Use renderer-owned wireframes unless the user
+  explicitly asks for branded, pixel-accurate, production-like, or full visual
+  design. This keeps every canvas screen inspectable and its full content visible.
 - **Prototype-first** when the user asks to operate the UI or when interaction is
   the main question. Use `create-prototype-plan`, which still preserves static
   mocks where useful.
@@ -354,6 +359,28 @@ For a worked example of the bar — a great UI-first plan and `/visual-plan`, pl
 the anti-patterns to avoid — READ `references/exemplar.md` in this skill
 directory before authoring a plan.
 
+## Authoring invariants
+
+Treat these as data-integrity checks, not optional polish:
+
+- `content` is a complete replacement. Pass either `content` or the mode's
+  convenience arrays (`screens`/`transitions` or `states`/`components`),
+  never both. The create actions reject mixed sources so a second payload cannot
+  silently discard CSS, frames, or document blocks.
+- A design screen's scoped `css` is part of the artifact. Keep it on both the
+  prototype screen and its matching canvas frame, and use renderer-owned
+  `--wf-*` tokens for portable color and typography.
+- Rich-text `data.markdown` must contain actual runtime line breaks. Do not
+  hand a plan a one-line Markdown value containing literal `\n` escape text,
+  which renders the whole section as one heading. Escaped newlines are fine in
+  code examples when the surrounding Markdown still has real line breaks.
+- Canvas artboards do not scroll. Keep wireframe HTML in natural flow and set a
+  larger frame `height` when a screen exceeds the surface preset; preserve the
+  surface width and inspect the bottom edge at default zoom before handoff.
+- After every hosted write, re-read the structured content and inspect the live
+  Plan surface. A valid JSON payload is not proof that CSS loaded or Markdown
+  rendered into the intended heading, paragraph, and list structure.
+
 ## Tool Guidance
 
 - `create-visual-plan`: start one structured visual plan per agent task/run, or

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

@@ -7,10 +7,12 @@ canvas layouts from memory or paraphrase these rules per mode.
 
 <!-- SHARED-CORE:canvas-surface START -->
 
-**The coordinate rule.** The `surface` locks each artboard's footprint and
-aspect — never set artboard width/height and never use coordinates inside the
-wireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear
-lanes. Let canvas auto-placement handle simple one-row boards.
+**The coordinate rule.** The `surface` sets each artboard's default footprint
+and width — never set width or use coordinates inside the wireframe HTML.
+Board-level artboard `x`/`y` IS allowed when it creates clear lanes. A
+larger explicit artboard `height` is allowed when the screen's content needs
+more vertical room; canvas frames do not scroll, so reserve enough height to
+show the entire UI. Let canvas auto-placement handle simple one-row boards.
 
 **Lay out mixed canvases in lanes.** When a canvas contains broad browser /
 desktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put
@@ -34,6 +36,14 @@ and move any frame whose label, connector, or annotation crosses another frame.
 
 When in doubt, use larger values — the canvas auto-zooms to fit everything.
 
+**Full-content artboards.** Canvas frames are pan/zoom surfaces, not scroll
+containers. Keep wireframe HTML in natural document flow without an inner
+scroll region or fixed child height. If the screen is taller than the default
+surface preset, set the artboard's `height` to the measured content height plus
+breathing room; keep the surface width unchanged. Before handoff, inspect the
+bottom edge of every artboard at default zoom and confirm no control, row, or
+footer is clipped.
+
 **Canvas annotations are designer notes on the artboard.** When a top canvas is
 present, sprinkle design-review notes near the frames they explain: a short
 heading, supporting text, and bullets — plain text layers, never bordered or

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

@@ -192,6 +192,13 @@ create the breathing room. Keep text away from borders: every container, field,
 button, menu item, and annotation needs enough padding and line-height to read
 cleanly in the rendered Plan view.
 
+**Center page-like content inside broad surfaces.** For browser or desktop
+screens, let the outer root provide the full-width frame and padding, then keep
+the page body in a centered wrapper such as
+`width:100%;max-width:720px;margin-inline:auto`. Full-width app bars may span
+the root, but onboarding, auth, settings, and other page-like content should
+not hug the left border unless the real product does.
+
 **For feature-cloud or abundance visuals, optimize the composition over line-by-line
 reading.** Some marketing/product sections need to feel like a large surface area
 of capability rather than a precise app workflow. In those cases, use one padded

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

@@ -192,6 +192,13 @@ create the breathing room. Keep text away from borders: every container, field,
 button, menu item, and annotation needs enough padding and line-height to read
 cleanly in the rendered Plan view.
 
+**Center page-like content inside broad surfaces.** For browser or desktop
+screens, let the outer root provide the full-width frame and padding, then keep
+the page body in a centered wrapper such as
+`width:100%;max-width:720px;margin-inline:auto`. Full-width app bars may span
+the root, but onboarding, auth, settings, and other page-like content should
+not hug the left border unless the real product does.
+
 **For feature-cloud or abundance visuals, optimize the composition over line-by-line
 reading.** Some marketing/product sections need to feel like a large surface area
 of capability rather than a precise app workflow. In those cases, use one padded

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

@@ -38,6 +38,7 @@ import {
   agentPlanContentSchema,
   planContentSchema,
 } from "../shared/plan-content.js";
+import { rejectMixedPlanSources } from "./validate-plan-input.js";
 
 const designSurfaceSchema = z.enum([
   "desktop",
@@ -104,7 +105,7 @@ const designContextRecordSchema = z.record(z.string(), z.unknown()).refine(
 );
 
 const CONTENT_DESCRIPTION =
-  "Full structured content when the caller has already authored the design/prototype. Prefer screens/transitions for normal /plan-design creation.";
+  "Full structured content when the caller has already authored the design/prototype. This is a complete replacement: do not pass screens or transitions alongside it, or screen CSS and other content will be rejected as conflicting input. 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
@@ -180,11 +181,12 @@ const createPlanDesignSchema = z.object({
 
 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: createPlanDesignSchema.refine(
-    (args) => Boolean(args.brief || args.goal),
-    { message: "Either brief or goal is required." },
-  ),
+    "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. Pass either screens/transitions or one complete content payload, never both. Publish via this tool; never deliver the plan as inline chat text.",
+  schema: createPlanDesignSchema
+    .superRefine(rejectMixedPlanSources)
+    .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.

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

@@ -38,6 +38,7 @@ import {
   agentPlanContentSchema,
   planContentSchema,
 } from "../shared/plan-content.js";
+import { rejectMixedPlanSources } from "./validate-plan-input.js";
 
 const prototypeSurfaceSchema = z.enum([
   "desktop",
@@ -108,7 +109,7 @@ const prototypeTransitionSchema = z.object({
 });
 
 const CONTENT_DESCRIPTION =
-  "Full structured content when the caller has already authored a prototype. Prefer screens/transitions unless replacing the whole document.";
+  "Full structured content when the caller has already authored a prototype. This is a complete replacement: do not pass screens or transitions alongside it, or prototype CSS and other content will be rejected as conflicting input. 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
@@ -167,11 +168,12 @@ const createPrototypePlanSchema = z.object({
 
 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. If a functional prototype must also be high fidelity, set renderMode to "design" and put scoped styles in css; never embed style tags in html because they are rejected. Publish via this tool; never deliver the plan as inline chat text.',
-  schema: createPrototypePlanSchema.refine(
-    (args) => Boolean(args.brief || args.goal),
-    { message: "Either brief or goal is required." },
-  ),
+    '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. If a functional prototype must also be high fidelity, set renderMode to "design" and put scoped styles in css; never embed style tags in html because they are rejected. Pass either screens/transitions or one complete content payload, never both. Publish via this tool; never deliver the plan as inline chat text.',
+  schema: createPrototypePlanSchema
+    .superRefine(rejectMixedPlanSources)
+    .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.

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

@@ -38,6 +38,7 @@ import {
   agentPlanContentSchema,
   planContentSchema,
 } from "../shared/plan-content.js";
+import { rejectMixedPlanSources } from "./validate-plan-input.js";
 
 const uiPlanStateSchema = z.object({
   name: z.string().min(1).describe("State or screen name"),
@@ -56,7 +57,7 @@ const uiPlanComponentSchema = z.object({
 });
 
 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.';
+  'Structured editable UI plan content. This is a complete replacement: do not pass states or components alongside it, or canvas content will be rejected as conflicting input. 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
@@ -112,13 +113,12 @@ const createUiPlanSchema = z.object({
 
 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: createUiPlanSchema.refine(
-    (args) => Boolean(args.brief || args.goal),
-    {
+    "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. Pass either states/components or one complete content payload, never both. Publish via this tool; never deliver the plan as inline chat text.",
+  schema: createUiPlanSchema
+    .superRefine(rejectMixedPlanSources)
+    .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.

package/corpus/templates/plan/actions/get-plan-blocks.ts

@@ -33,6 +33,8 @@ const AUTHORING_RULES_NOTE = `
 
 **Wireframes**: set \`data.html\` to a semantic HTML fragment; pick a surface (desktop/mobile/popover/panel/browser). The renderer owns theme, footprint/aspect, Excalifont, and rough.js sketch overlay. Use \`--wf-*\` CSS tokens for any custom color (never hex). Prototype screens use semantic HTML with \`data-goto\` attributes for navigation.
 
+**Page alignment**: for browser or desktop page-like screens, give the outer root explicit padding and keep the body in a centered wrapper such as \`width:100%;max-width:720px;margin-inline:auto\`. Full-width app bars may span the root, but onboarding, auth, settings, and other page content should not hug the artboard edge unless the real product does.
+
 **Visual frames**: \`wireframe\` and \`diagram\` data accept \`frame: "auto" | "show" | "hide"\`. Leave it unset/\`auto\` when the host context should decide: Plan and recap surfaces default to framed; docs default to unframed. Use \`frame: "show"\` for standalone product screens, before/after recap comparisons, screenshot-like artifacts, and visuals that need containment from surrounding prose. Use \`frame: "hide"\` when a docs page, tab, column, card, canvas artboard, or the visual's own internal chrome already supplies the boundary. Hiding the outer frame must not remove inner padding, meaningful card/field/button borders, or the visual's readable structure.
 
 **Canvas storyboards**: if the user asks for a canvas, storyboard, wireframe, light storyboard, UI flow, screen flow, product flow, mockup, or visual comparison, the primary artifact must be \`content.canvas\` / \`canvas.mdx\` with \`DesignBoard\` artboards containing \`Screen\` HTML wireframes. Each canvas \`Screen\` must carry \`html\` / \`data.html\`; never author fresh nested kit-tree children such as \`<FrameScreen>\`, \`<Card>\`, \`<Row>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags. Kit trees are old-plan compatibility only and often render worse on the pan/zoom canvas than HTML wireframes. Do not use document-body \`diagram\` blocks for the primary UI story. Use \`diagram\` only for architecture, data flow, or implementation mechanics below the canvas, and only after the UI storyboard exists.
@@ -49,7 +51,11 @@ const AUTHORING_RULES_NOTE = `
 
 **API endpoints**: keep \`api-endpoint\` and \`openapi-spec\` blocks in normal single-column document flow. Use \`columns\` only for an explicit before/after contract comparison.
 
-**Visual fidelity and renderMode**: leave \`renderMode\` unset or set it to \`wireframe\` for normal wireframes. “Higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,” “real design,” or “not a sketch/wireframe” requires \`renderMode: "design"\`, substantial branded HTML/CSS grounded in the real app, and stable \`data-design-id\` targets. Put scoped styles in the wireframe/prototype \`css\` field — never in a \`<style>\` tag. On an existing plan, update the same plan id with \`set-visual-render-mode\` plus the upgraded HTML/CSS; do not create a duplicate. The viewer-local Clean toggle is not a fidelity upgrade.\``;
+**Visual fidelity and renderMode**: leave \`renderMode\` unset or set it to \`wireframe\` for normal wireframes. “Clean,” “minimal,” “high UX bar,” or Linear/Vercel references set the content and density bar, not full-fidelity mode. Only explicit “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,” “real design,” or “not a sketch/wireframe” requires \`renderMode: "design"\`, substantial branded HTML/CSS grounded in the real app, and stable \`data-design-id\` targets. Put scoped styles in the wireframe/prototype \`css\` field — never in a \`<style>\` tag. On an existing plan, update the same plan id with \`set-visual-render-mode\` plus the upgraded HTML/CSS; do not create a duplicate. The viewer-local Clean toggle is not a fidelity upgrade.
+
+**Canvas fit**: canvas artboards are pan/zoom surfaces and do not scroll. Keep wireframe HTML in natural flow without an inner scroll region. If a screen is taller than the surface preset, set the artboard's explicit \`height\` larger than the default while keeping its surface width unchanged, then inspect the bottom edge at default zoom so no row, control, or footer is clipped.
+
+**Payload integrity**: \`content\` is a complete replacement. Pass either \`content\` or the mode-specific convenience arrays (\`screens\`/\`transitions\` or \`states\`/\`components\`), never both; mixed inputs are rejected so CSS and blocks cannot disappear silently. For design content, keep the same HTML/CSS in the prototype screens and canvas frames. Rich-text \`data.markdown\` must contain real runtime line breaks; a one-line value containing literal \`\\n\` escape text will render as one giant heading and is rejected. After writing, re-read the structured plan and inspect the actual Plan surface before handoff.\``;
 
 /**
  * Expose the live plan block vocabulary to the agent. The list is generated from

package/corpus/templates/plan/actions/validate-plan-input.ts

@@ -0,0 +1,39 @@
+import type { RefinementCtx } from "zod";
+
+type PlanInputSources = {
+  content?: unknown;
+  screens?: readonly unknown[];
+  transitions?: readonly unknown[];
+  states?: readonly unknown[];
+  components?: readonly unknown[];
+};
+
+/**
+ * A full content payload is a replacement, not a second source to merge with
+ * the convenience arrays. Rejecting mixed inputs keeps screen CSS and blocks
+ * from being silently discarded at the action boundary.
+ */
+export function rejectMixedPlanSources(
+  value: PlanInputSources,
+  ctx: RefinementCtx,
+): void {
+  if (!value.content) return;
+
+  const conflictingFields = [
+    ["screens", value.screens],
+    ["transitions", value.transitions],
+    ["states", value.states],
+    ["components", value.components],
+  ] as const;
+
+  for (const [field, entries] of conflictingFields) {
+    if (!entries || entries.length === 0) continue;
+    ctx.addIssue({
+      code: "custom",
+      path: [field],
+      message:
+        `content is a complete visual-plan replacement; do not pass ${field} ` +
+        "alongside it. Remove content or provide the full content payload.",
+    });
+  }
+}