@agent-native/core 0.39.0 → 0.39.2

package/dist/cli/skills.js

@@ -15,7 +15,7 @@ const HELP = `agent-native skills
 
 Usage:
   agent-native skills list
-  agent-native skills add assets|design-exploration|visual-plan|visual-questions|ui-plan|prototype-plan|visualize-plan|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--yes] [--dry-run] [--json]
+  agent-native skills add assets|design-exploration|visual-plan|visual-questions|ui-plan|prototype-plan|plan-design|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--yes] [--dry-run] [--json]
   agent-native skills add <manifest-or-app-dir> [--client ...] [--yes]
 
 Examples:
@@ -196,7 +196,7 @@ iteration, or a human-in-the-loop choice among design directions.
 `;
 /**
  * Shared setup/auth block for every Plans skill (`/visual-plan`, `/ui-plan`,
- * `/prototype-plan`, `/visual-questions`, `/visualize-plan`). Interpolated into each skill markdown
+ * `/prototype-plan`, `/plan-design`, `/visual-questions`). Interpolated into each skill markdown
  * so the install + one-step authenticate instructions never drift between them.
  * Keep this in sync with the copies under `templates/plan/.agents/skills/*` and
  * top-level `skills/*` (this skill's SKILL.md is triplicated with no sync test).
@@ -214,8 +214,8 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`,
+\`/visual-questions\`) generate a plan and open the editor. Pass \`--no-connect\` to
 register the connector without authenticating, then run
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
@@ -242,8 +242,8 @@ export const VISUAL_PLANS_SKILL_MD = `---
 name: visual-plan
 description: >-
   Use Agent-Native Plans when coding-agent work needs an interactive structured
-  plan document with diagrams, wireframes, mockups, prototypes, annotations,
-  and comments.
+  plan document with inline diagrams, implementation maps, optional UI/product
+  wireframes or prototypes, annotations, and comments.
 metadata:
   visibility: exported
 ---
@@ -252,23 +252,29 @@ metadata:
 
 Agent-Native Plans is structured visual planning mode for coding agents. Build
 the plan you would normally write in Markdown, but as a scannable document with
-editable blocks mixed in: an optional top visual review area (wireframe canvas,
-live prototype, or both in tabs) and a Notion-like technical document below. The
-user reacts to visuals first and reads prose only where it helps.
+editable blocks mixed in: inline diagrams, implementation maps, code previews,
+open questions, and an optional top visual review area (wireframe canvas, live
+prototype, or both in tabs). Architecture, backend, data, and refactor plans
+usually start in the document with local diagrams near each claim. UI and product
+plans should still start with the top canvas/prototype when screens or behavior
+are what the user needs to review.
 
 \`/visual-plan\` is the canonical command and the main entry point. Use \`/ui-plan\`
 when the work is primarily product UI and review should start with the screens.
 Use \`/prototype-plan\` when review should start with a functional live prototype.
+Use \`/plan-design\` when review should start with full-fidelity branded design.
 Use \`/visual-questions\` only when the user explicitly wants a visual intake form
-before planning. Use \`/visualize-plan\` to turn an existing Codex, Claude Code,
-Markdown, or pasted plan into a visual companion.
+before planning. When a Codex, Claude Code, Markdown, or pasted plan already
+exists, \`/visual-plan\` uses that source plan as the starting point and builds
+the review surface from it instead of starting over.
 
 ## When To Use
 
-Create a visual plan when work is multi-file, ambiguous, long-running, risky, or
-UI-heavy, when architecture / data flow / UI direction / options / open
-questions would be clearer visually, or when the user needs to react to a
-direction before you implement.
+Create or adapt a visual plan when work is multi-file, ambiguous, long-running,
+risky, or UI-heavy, when architecture / data flow / UI direction / options /
+open questions would benefit from inline diagrams or structured blocks, when the
+user needs to react to a direction before you implement, or when an existing text
+plan needs a richer review surface.
 
 ## Plan Discipline
 
@@ -281,6 +287,10 @@ direction before you implement.
   patterns first; name actual files, symbols, and data shapes instead of
   inventing them. Check existing \`actions/\` before proposing endpoints and prefer
   named client helpers over raw fetch. Delegate wide exploration to a sub-agent.
+- **Preserve existing plans.** If the user pasted, referenced, or already has a
+  Codex / Claude Code / Markdown plan, treat it as source material. Preserve its
+  intent, do not invent codebase facts, label inferred visuals as inferred, and
+  build the visual review structure around the plan the user already has.
 - **Planning is read-only.** Make no source edits while building or reviewing the
   plan. Start editing only after the user approves the direction.
 - **Clarify vs. assume.** Do not ask how to build it — explore and present the
@@ -303,19 +313,32 @@ direction before you implement.
 
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
    wide exploration when useful, gather the info needed, and ask native
-   clarifying questions as needed before generating the plan.
-2. Decide the top visual surface with the rules below, then call
-   \`create-visual-plan\` with the title, brief, source, repo path, and structured \`content\` blocks.
-3. Compose any top visual surface from the kit and write the document with
-   native blocks (see the cores below). Keep the document close to the Markdown
-   plan the agent would normally output; add diagrams, wireframes, prototypes,
-   and visual callouts only where they clarify the plan. Skip the top visual
-   surface for non-visual work.
+   clarifying questions as needed before generating the plan. If a source plan
+   already exists, gather its exact text from the user's paste, a referenced
+   file, or recent visible agent context; do not invent source text.
+2. Decide whether the plan needs a top visual surface with the rules below, then call
+   \`create-visual-plan\` with the title, brief, source, repo path, and structured
+   \`content\` blocks. When a source plan already exists, pass it as \`planText\`
+   and preserve the original plan's intent while adding structured review
+   content.
+3. Compose or enrich any top UI/product visual surface from the kit and write the
+   document with native blocks (see the cores below). Keep the document close to
+   the Markdown plan the agent would normally output, or to the existing plan
+   when one was provided. For architecture, backend, refactor, API, data-model,
+   migration, or code plans, usually omit \`content.canvas\` and
+   \`content.prototype\`; put \`diagram\`, \`mermaid\`, \`data-model\`, \`file-tree\`,
+   \`implementation-map\`, \`code-tabs\`, and \`annotated-code\` blocks directly next
+   to the relevant prose. Skip the top visual surface for non-visual work.
 4. Surface the returned Plans link or inline MCP App and ask the user to review.
    Always include the actual URL in chat so the next step is a click in CLI or
    other text-only hosts. When the host exposes an embedded browser/preview panel
    and a tool can open arbitrary URLs there, open the returned plan URL
    automatically for convenient review; do not rely on this as the only handoff.
+   Treat that browser open as a convenience and smoke test, not as the access
+   model. Plans should load out of the box for the local agent and local browser
+   session; if a signed-in embedded browser cannot read a local plan that an
+   anonymous/tool check can read, fix the app/action ownership or access path
+   rather than patching one plan by hand.
 5. Call \`get-plan-feedback\` before editing, after review, after any long pause,
    and before the final response. Treat \`anchorDetails\`, resolver intent, recent
    review events, and any focused screenshots from browser handoff as the source
@@ -329,12 +352,17 @@ direction before you implement.
 
 ## Visual Surface Choice
 
-Choose the surface before creating the plan. Do not add visual chrome by
-default:
+Choose the surface before creating the plan or after reading the source plan. Do
+not add visual chrome by default:
 
 - **No visual surface** for architecture-only, backend-only, data migration,
-  copy-only, or otherwise non-visual plans. Use a strong document with diagrams
-  only when relationships need a visual explanation.
+  copy-only, or otherwise non-visual plans. Do not use the top canvas for
+  architecture diagrams, dependency maps, file plans, API contracts, or
+  data-flow-only reviews. Use a strong document with local inline diagrams
+  only when relationships need a visual explanation, usually one spatial diagram
+  per recommendation or decision. Prefer grouped regions, layers, quadrants,
+  matrices, or before/after panels over a single-axis chain unless the
+  relationship is truly sequential.
 - **Canvas only** for one static screen, a before/after comparison, a component
   state, a small popover, or a visual direction that does not require clicking.
   Put those wireframes in \`content.canvas\` and omit \`content.prototype\`.
@@ -356,9 +384,9 @@ design direction.
 
 ## Wireframe & Canvas Core
 
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for how wireframes and the
-canvas work. Do not paraphrase it per command.
+This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
+the single source of truth for how wireframes and the canvas work. Do not
+paraphrase it per command.
 
 **A wireframe is an HTML mockup. The renderer owns the look; you write the
 content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
@@ -425,6 +453,15 @@ the current screen's real layout and footprint FIRST, then change only the delta
 and call it out with a single annotation. Do not restack the page into a new
 layout. For net-new surfaces, compose from the real app shell.
 
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+
 **Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
 popover, menu, dialog, toast), show the full screen once, then add a small
 separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
@@ -478,7 +515,15 @@ In the browser, humans edit \`rich-text\` prose inline; agents should still use
 \`update-rich-text\` content patches or source patches for prose, and use
 comments/structured patches for canvas, artboard, wireframe, and diagram edits.
 
-**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
+**Never emit a titled artboard with no interior wireframe content.** Every artboard
+you place on the canvas must carry an \`html\` wireframe or reference a wireframe
+block via \`blockId\`; when using \`blockId\`, the referenced \`wireframe\` /
+\`legacy-wireframe\` block must remain in the plan. If you remove a duplicate
+wireframe from the document body, first move its \`data\` inline onto the
+corresponding \`content.canvas.frames[*].wireframe\` / \`legacyWireframe\`. A
+label-only frame or a frame pointing at a deleted block renders empty and is
+rejected at parse time. If you only have a title, write it as a section header or
+annotation, not an empty artboard.
 
 **Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
 
@@ -487,7 +532,9 @@ composed from the helper classes and tokens, layout in inline flex, no fonts or
 hex colors:
 
 \`\`\`html
-<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
   <div style="display:flex;align-items:center;justify-content:space-between">
     <h1>Contacts</h1>
     <button class="primary">New contact</button>
@@ -497,33 +544,48 @@ hex colors:
     <span class="wf-pill">Favorites</span>
     <span class="wf-pill">Archived</span>
   </div>
-  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
-    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
       <span class="wf-pill">Lead</span>
     </div>
     <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
       <span class="wf-pill">Customer</span>
     </div>
   </div>
 </div>
 \`\`\`
 
-**Mockups belong in the top visual review area.** Static visuals live on the
-canvas; multi-step flows get both canvas wireframes and a prototype. When the
-user asks for a mockup, UI state, loading state, layout, screen, or visual
-comparison, make the canvas the primary home for that static visual. When the
-user asks for a prototype or the plan contains a sequence the reviewer must
-feel, keep the canvas artboards and add \`content.prototype\` so the top surface
-shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
-implementation, but they should not host the primary mockup or prototype just
-because \`custom-html\`, screenshots, or prose are easier to produce. If the
-canvas/prototype surface cannot represent the requested fidelity, still keep the
-closest top-surface representation and call out or extend the needed renderer
-capability.
+**UI mockups belong in the top visual review area.** Static UI/product visuals
+live on the canvas; multi-step UI flows get both canvas wireframes and a
+prototype. When the user asks for a mockup, UI state, loading state, layout,
+screen, or visual comparison, make the canvas the primary home for that static
+visual. When the user asks for a prototype or the plan contains a sequence the
+reviewer must feel, keep the canvas artboards and add \`content.prototype\` so the
+top surface shows Wireframes / Prototype tabs. Architecture/code diagrams are
+different: keep them inline in the document, close to the recommendation they
+support, unless the user explicitly asks for a spatial board. Document blocks
+can explain, compare, or map implementation, but they should not host the
+primary UI mockup or prototype just because \`custom-html\`, screenshots, or prose
+are easier to produce. If the canvas/prototype surface cannot represent the
+requested UI fidelity, still keep the closest top-surface representation and
+call out or extend the needed renderer capability.
 
 **Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
 nodes instead of \`html\`; the renderer still accepts and displays it, but new
@@ -541,9 +603,9 @@ plan.
 
 ## Document Quality Core
 
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for the document below the
-canvas. Do not paraphrase it per command.
+This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
+the single source of truth for the document below the canvas. Do not paraphrase
+it per command.
 
 **The document is a serious technical plan, not marketing.** Write it the way a
 strong Claude or Codex implementation plan reads: outcome-first, prose-first,
@@ -555,14 +617,27 @@ behavior). Replace vague prose with specifics; never ship a step like "make it
 work." No hero art, gradients, logos, nav bars, slogans, value props, giant
 landing-page headings, or marketing cards unless the user explicitly asks.
 
-**Top visuals and document never duplicate each other.** The UI story lives in
-the top visual surface: canvas artboards for static inspection, plus prototype
-tabs when the flow should be functional. The document carries the technical depth
-the visuals cannot show — concrete file/symbol maps, API and data contracts,
-code snippets, migration or implementation phases, risks, and validation. Repeat
-a wireframe in the document only for a genuinely new detail view or comparison.
-Skip the visual surface entirely for non-visual work and write a clean rich
-document.
+**When top visuals exist, they and the document never duplicate each other.**
+For UI work, the UI story lives in the top visual surface: canvas artboards for
+static inspection, plus prototype tabs when the flow should be functional. The
+document carries the technical depth the visuals cannot show — concrete
+file/symbol maps, API and data contracts, code snippets, migration or
+implementation phases, risks, and validation. For architecture/code reviews,
+invert that: the document is the visual surface, and each recommendation should
+carry its own nearby inline \`diagram\` / \`data-model\` block plus file evidence
+and terse Problem/Solution/Why text. For architecture/code diagrams, prefer
+standard two-dimensional layouts: paired before/after panels, layered diagrams,
+swimlanes, dependency maps, matrices, or grouped regions. Do not default to
+left-to-right chains; use a line only when the relationship is truly a sequence.
+Use native \`diagram\` blocks with \`data.html\` / \`data.css\` for these richer
+layouts; the fragment may use semantic HTML and inline SVG, and the renderer
+applies the viewer's sketch/clean style. Legacy \`nodes\` / \`edges\` are only for
+tiny previews or genuinely linear step flows. Repeat a wireframe in the document
+only for a genuinely new detail view or comparison. Skip the visual surface
+entirely for non-visual work and write a clean rich document. For a simple
+binary UI visual choice, show the two directions in the canvas only; do not
+repeat the same options as body wireframes, a \`decision\` block, or prose. Put
+the actual choice in the bottom "Open Questions" form.
 
 **Use the right block, and make it carry substance.** For the authoritative,
 machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
@@ -572,14 +647,23 @@ so you never emit a block the editor cannot render or round-trip:
 - \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
 - \`implementation-map\` / \`code-tabs\` for the file map: file path, the
   symbols/components to touch, the reason, risk/coordination notes, and a
-  concise syntax-highlighted snippet of the code shape — never the whole file,
-  never a prose-only file list.
+  concise syntax-highlighted snippet of the code shape in every file tab —
+  never the whole file, never a prose-only file list. If the exact code is not
+  known yet, include the smallest plausible planned shape or a short comment
+  stub that names what needs to be filled in.
 - \`decision\` for two or three option cards with consequences. These are static
   records; do not style them like clickable tabs or chips unless the renderer
   truly supports changing the selection.
-- \`diagram\` for architecture, sequence, data-flow, dependency, or state
-  relationships, only when it clarifies something real. Labels must not overlap
-  nodes, connectors, or each other.
+- \`diagram\` for two-dimensional architecture, dependency, data-flow, or state
+  relationships, only when it clarifies something real. For architecture/code
+  diagrams, prefer \`data.html\` / \`data.css\` with semantic HTML and inline SVG so
+  the diagram can use panels, layers, matrices, arrows, annotations, and
+  responsive layout directly. Use legacy \`nodes\` / \`edges\` only for small
+  previews or truly sequential flows. In architecture/code plans, prefer a
+  repeated section rhythm: recommendation title, confidence and category badges,
+  code-path evidence, a local before/after or current/target spatial diagram,
+  then concise Problem/Solution/Why text. Labels must not overlap nodes,
+  connectors, or each other.
 - \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
   only prose usually means the plan is under-specified — include a relevant
   visual unless the tab is intentionally document-only.
@@ -587,21 +671,24 @@ so you never emit a block the editor cannot render or round-trip:
 
 **Open questions live at the bottom as a form when answers would change the
 plan.** Surface answerable unresolved decisions in a final \`question-form\`
-block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
-\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
-and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
-Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
-relevant section. Never bury a questions/decisions wall inside the plan
-narrative.
+block titled "Open Questions" so the renderer presents it as a distinct section.
+Use \`single\` or \`multi\` for clear choices, \`freeform\` for constraints,
+\`recommended: true\` for the default you would pick, and option \`wireframe\` /
+\`diagram\` previews only when the options are not already visible in the top
+canvas. Keep non-answerable assumptions or risks as concise \`callout\` blocks in
+the relevant section. Never bury a questions/decisions wall inside the plan
+narrative, and never ask the same question in both a \`decision\` block and a
+\`question-form\`.
 
 **\`custom-html\` is a bounded escape hatch only** — a single complete fragment
 inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
 placeholder, density demo, or proof that custom HTML works. Prefer the native
-blocks for normal plans. It may support supplemental demos or references, but it
-is never the primary home for a requested mockup, UI state, or visual
-comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
-product fix is canvas support for that artifact type, not moving the mockup into
-the document.
+blocks for normal plans. For architecture/code reviews, use \`diagram\`
+\`data.html\` / \`data.css\` for rich local HTML/SVG diagrams instead of
+\`custom-html\`. For UI/product work, \`custom-html\` is never the primary home for a
+requested mockup, UI state, or visual comparison. If UI fidelity requires
+HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
+for that artifact type, not moving the mockup into the document.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
@@ -629,6 +716,16 @@ changes a multi-step completion flow, the same top area includes a Prototype tab
 whose screens use the same labels and states as the canvas artboards, with
 \`data-goto\` controls for the sequence. This is the bar.
 
+**GOOD.** A \`/visual-plan\` for a backend architecture review: no top canvas.
+The document opens with context and a legend, then repeats recommendation cards:
+title, confidence/category badges, a monospace grid of real file paths, one
+inline two-dimensional before/after or layered architecture diagram, and terse
+Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
+space to show boundaries, layers, and ownership; it is not a default
+left-to-right chain. The plan ends with a top recommendation and a bottom
+question-form only if the next architecture direction is genuinely open. This is
+better than a top canvas because each diagram is local to the claim it supports.
+
 **BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
 pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
 frame; a forced desktop + mobile pair for a popover; floating bordered
@@ -636,22 +733,26 @@ annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
 instead of \`html\`; a multi-step UI flow with only static frames and no prototype
 tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
 document with a hero heading and value props that just restates what the canvas
-already shows. Never produce this.
+already shows. Also bad: an architecture-only plan forced into a top canvas of
+labeled boxes with overlapping text, where the actual code evidence and
+recommendations live elsewhere. Never produce this.
 
 <!-- SHARED-CORE:exemplar END -->
 
 ## Tool Guidance
 
-- \`create-visual-plan\`: start one structured visual plan per agent task/run;
-  \`content\` may include no visual surface, canvas only, or canvas + prototype.
+- \`create-visual-plan\`: start one structured visual plan per agent task/run, or
+  import an existing text plan by passing \`planText\`; \`content\` may include no
+  visual surface, canvas only, or canvas + prototype.
 - \`create-ui-plan\`: start a UI-first plan when the work is primarily product UI.
 - \`create-prototype-plan\`: start a prototype-first plan with a functional top
   review surface.
+- \`create-plan-design\`: start a full-fidelity branded Design-tab plan with an
+  optional matching Prototype tab.
 - \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
   into a prototype plan.
 - \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
   command, not as \`/visual-plan\` preflight.
-- \`visualize-plan\`: build a visual companion from an existing text plan.
 - \`update-visual-plan\`: revise content, status, or comments; prefer
   \`contentPatches\` over regenerating the whole plan.
 - \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
@@ -683,8 +784,8 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`,
+\`/visual-questions\`) generate a plan and open the editor. Pass \`--no-connect\` to
 register the connector without authenticating, then run
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
@@ -727,9 +828,10 @@ react to.
 
 \`/visual-plan\` remains the general command for architecture, backend, refactors,
 and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
-prototype instead of static screens. Use \`/visual-questions\` only when the user
-explicitly wants visual intake before planning, and \`/visualize-plan\` when a text
-plan already exists.
+prototype instead of static screens. Use \`/plan-design\` when polish, brand, or
+visual fidelity are material to the decision. Use \`/visual-questions\` only when
+the user explicitly wants visual intake before planning. Use \`/visual-plan\` when
+a text plan already exists and should become the source material for the review.
 
 ## Plan Discipline
 
@@ -785,9 +887,9 @@ the user has supplied it.
 
 ## Wireframe & Canvas Core
 
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for how wireframes and the
-canvas work. Do not paraphrase it per command.
+This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
+the single source of truth for how wireframes and the canvas work. Do not
+paraphrase it per command.
 
 **A wireframe is an HTML mockup. The renderer owns the look; you write the
 content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
@@ -854,6 +956,15 @@ the current screen's real layout and footprint FIRST, then change only the delta
 and call it out with a single annotation. Do not restack the page into a new
 layout. For net-new surfaces, compose from the real app shell.
 
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+
 **Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
 popover, menu, dialog, toast), show the full screen once, then add a small
 separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
@@ -907,7 +1018,15 @@ In the browser, humans edit \`rich-text\` prose inline; agents should still use
 \`update-rich-text\` content patches or source patches for prose, and use
 comments/structured patches for canvas, artboard, wireframe, and diagram edits.
 
-**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
+**Never emit a titled artboard with no interior wireframe content.** Every artboard
+you place on the canvas must carry an \`html\` wireframe or reference a wireframe
+block via \`blockId\`; when using \`blockId\`, the referenced \`wireframe\` /
+\`legacy-wireframe\` block must remain in the plan. If you remove a duplicate
+wireframe from the document body, first move its \`data\` inline onto the
+corresponding \`content.canvas.frames[*].wireframe\` / \`legacyWireframe\`. A
+label-only frame or a frame pointing at a deleted block renders empty and is
+rejected at parse time. If you only have a title, write it as a section header or
+annotation, not an empty artboard.
 
 **Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
 
@@ -916,7 +1035,9 @@ composed from the helper classes and tokens, layout in inline flex, no fonts or
 hex colors:
 
 \`\`\`html
-<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
   <div style="display:flex;align-items:center;justify-content:space-between">
     <h1>Contacts</h1>
     <button class="primary">New contact</button>
@@ -926,33 +1047,48 @@ hex colors:
     <span class="wf-pill">Favorites</span>
     <span class="wf-pill">Archived</span>
   </div>
-  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
-    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
       <span class="wf-pill">Lead</span>
     </div>
     <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
       <span class="wf-pill">Customer</span>
     </div>
   </div>
 </div>
 \`\`\`
 
-**Mockups belong in the top visual review area.** Static visuals live on the
-canvas; multi-step flows get both canvas wireframes and a prototype. When the
-user asks for a mockup, UI state, loading state, layout, screen, or visual
-comparison, make the canvas the primary home for that static visual. When the
-user asks for a prototype or the plan contains a sequence the reviewer must
-feel, keep the canvas artboards and add \`content.prototype\` so the top surface
-shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
-implementation, but they should not host the primary mockup or prototype just
-because \`custom-html\`, screenshots, or prose are easier to produce. If the
-canvas/prototype surface cannot represent the requested fidelity, still keep the
-closest top-surface representation and call out or extend the needed renderer
-capability.
+**UI mockups belong in the top visual review area.** Static UI/product visuals
+live on the canvas; multi-step UI flows get both canvas wireframes and a
+prototype. When the user asks for a mockup, UI state, loading state, layout,
+screen, or visual comparison, make the canvas the primary home for that static
+visual. When the user asks for a prototype or the plan contains a sequence the
+reviewer must feel, keep the canvas artboards and add \`content.prototype\` so the
+top surface shows Wireframes / Prototype tabs. Architecture/code diagrams are
+different: keep them inline in the document, close to the recommendation they
+support, unless the user explicitly asks for a spatial board. Document blocks
+can explain, compare, or map implementation, but they should not host the
+primary UI mockup or prototype just because \`custom-html\`, screenshots, or prose
+are easier to produce. If the canvas/prototype surface cannot represent the
+requested UI fidelity, still keep the closest top-surface representation and
+call out or extend the needed renderer capability.
 
 **Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
 nodes instead of \`html\`; the renderer still accepts and displays it, but new
@@ -970,9 +1106,9 @@ plan.
 
 ## Document Quality Core
 
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for the document below the
-canvas. Do not paraphrase it per command.
+This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
+the single source of truth for the document below the canvas. Do not paraphrase
+it per command.
 
 **The document is a serious technical plan, not marketing.** Write it the way a
 strong Claude or Codex implementation plan reads: outcome-first, prose-first,
@@ -984,14 +1120,27 @@ behavior). Replace vague prose with specifics; never ship a step like "make it
 work." No hero art, gradients, logos, nav bars, slogans, value props, giant
 landing-page headings, or marketing cards unless the user explicitly asks.
 
-**Top visuals and document never duplicate each other.** The UI story lives in
-the top visual surface: canvas artboards for static inspection, plus prototype
-tabs when the flow should be functional. The document carries the technical depth
-the visuals cannot show — concrete file/symbol maps, API and data contracts,
-code snippets, migration or implementation phases, risks, and validation. Repeat
-a wireframe in the document only for a genuinely new detail view or comparison.
-Skip the visual surface entirely for non-visual work and write a clean rich
-document.
+**When top visuals exist, they and the document never duplicate each other.**
+For UI work, the UI story lives in the top visual surface: canvas artboards for
+static inspection, plus prototype tabs when the flow should be functional. The
+document carries the technical depth the visuals cannot show — concrete
+file/symbol maps, API and data contracts, code snippets, migration or
+implementation phases, risks, and validation. For architecture/code reviews,
+invert that: the document is the visual surface, and each recommendation should
+carry its own nearby inline \`diagram\` / \`data-model\` block plus file evidence
+and terse Problem/Solution/Why text. For architecture/code diagrams, prefer
+standard two-dimensional layouts: paired before/after panels, layered diagrams,
+swimlanes, dependency maps, matrices, or grouped regions. Do not default to
+left-to-right chains; use a line only when the relationship is truly a sequence.
+Use native \`diagram\` blocks with \`data.html\` / \`data.css\` for these richer
+layouts; the fragment may use semantic HTML and inline SVG, and the renderer
+applies the viewer's sketch/clean style. Legacy \`nodes\` / \`edges\` are only for
+tiny previews or genuinely linear step flows. Repeat a wireframe in the document
+only for a genuinely new detail view or comparison. Skip the visual surface
+entirely for non-visual work and write a clean rich document. For a simple
+binary UI visual choice, show the two directions in the canvas only; do not
+repeat the same options as body wireframes, a \`decision\` block, or prose. Put
+the actual choice in the bottom "Open Questions" form.
 
 **Use the right block, and make it carry substance.** For the authoritative,
 machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
@@ -1001,14 +1150,23 @@ so you never emit a block the editor cannot render or round-trip:
 - \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
 - \`implementation-map\` / \`code-tabs\` for the file map: file path, the
   symbols/components to touch, the reason, risk/coordination notes, and a
-  concise syntax-highlighted snippet of the code shape — never the whole file,
-  never a prose-only file list.
+  concise syntax-highlighted snippet of the code shape in every file tab —
+  never the whole file, never a prose-only file list. If the exact code is not
+  known yet, include the smallest plausible planned shape or a short comment
+  stub that names what needs to be filled in.
 - \`decision\` for two or three option cards with consequences. These are static
   records; do not style them like clickable tabs or chips unless the renderer
   truly supports changing the selection.
-- \`diagram\` for architecture, sequence, data-flow, dependency, or state
-  relationships, only when it clarifies something real. Labels must not overlap
-  nodes, connectors, or each other.
+- \`diagram\` for two-dimensional architecture, dependency, data-flow, or state
+  relationships, only when it clarifies something real. For architecture/code
+  diagrams, prefer \`data.html\` / \`data.css\` with semantic HTML and inline SVG so
+  the diagram can use panels, layers, matrices, arrows, annotations, and
+  responsive layout directly. Use legacy \`nodes\` / \`edges\` only for small
+  previews or truly sequential flows. In architecture/code plans, prefer a
+  repeated section rhythm: recommendation title, confidence and category badges,
+  code-path evidence, a local before/after or current/target spatial diagram,
+  then concise Problem/Solution/Why text. Labels must not overlap nodes,
+  connectors, or each other.
 - \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
   only prose usually means the plan is under-specified — include a relevant
   visual unless the tab is intentionally document-only.
@@ -1016,21 +1174,24 @@ so you never emit a block the editor cannot render or round-trip:
 
 **Open questions live at the bottom as a form when answers would change the
 plan.** Surface answerable unresolved decisions in a final \`question-form\`
-block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
-\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
-and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
-Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
-relevant section. Never bury a questions/decisions wall inside the plan
-narrative.
+block titled "Open Questions" so the renderer presents it as a distinct section.
+Use \`single\` or \`multi\` for clear choices, \`freeform\` for constraints,
+\`recommended: true\` for the default you would pick, and option \`wireframe\` /
+\`diagram\` previews only when the options are not already visible in the top
+canvas. Keep non-answerable assumptions or risks as concise \`callout\` blocks in
+the relevant section. Never bury a questions/decisions wall inside the plan
+narrative, and never ask the same question in both a \`decision\` block and a
+\`question-form\`.
 
 **\`custom-html\` is a bounded escape hatch only** — a single complete fragment
 inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
 placeholder, density demo, or proof that custom HTML works. Prefer the native
-blocks for normal plans. It may support supplemental demos or references, but it
-is never the primary home for a requested mockup, UI state, or visual
-comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
-product fix is canvas support for that artifact type, not moving the mockup into
-the document.
+blocks for normal plans. For architecture/code reviews, use \`diagram\`
+\`data.html\` / \`data.css\` for rich local HTML/SVG diagrams instead of
+\`custom-html\`. For UI/product work, \`custom-html\` is never the primary home for a
+requested mockup, UI state, or visual comparison. If UI fidelity requires
+HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
+for that artifact type, not moving the mockup into the document.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
@@ -1058,6 +1219,16 @@ changes a multi-step completion flow, the same top area includes a Prototype tab
 whose screens use the same labels and states as the canvas artboards, with
 \`data-goto\` controls for the sequence. This is the bar.
 
+**GOOD.** A \`/visual-plan\` for a backend architecture review: no top canvas.
+The document opens with context and a legend, then repeats recommendation cards:
+title, confidence/category badges, a monospace grid of real file paths, one
+inline two-dimensional before/after or layered architecture diagram, and terse
+Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
+space to show boundaries, layers, and ownership; it is not a default
+left-to-right chain. The plan ends with a top recommendation and a bottom
+question-form only if the next architecture direction is genuinely open. This is
+better than a top canvas because each diagram is local to the claim it supports.
+
 **BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
 pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
 frame; a forced desktop + mobile pair for a popover; floating bordered
@@ -1065,7 +1236,9 @@ annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
 instead of \`html\`; a multi-step UI flow with only static frames and no prototype
 tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
 document with a hero heading and value props that just restates what the canvas
-already shows. Never produce this.
+already shows. Also bad: an architecture-only plan forced into a top canvas of
+labeled boxes with overlapping text, where the actual code evidence and
+recommendations live elsewhere. Never produce this.
 
 <!-- SHARED-CORE:exemplar END -->
 
@@ -1074,6 +1247,8 @@ already shows. Never produce this.
 - \`create-ui-plan\`: create the UI-first structured visual plan.
 - \`create-prototype-plan\`: create a prototype-first plan when UI review needs a
   functional live prototype.
+- \`create-plan-design\`: create a full-fidelity branded design plan when polish,
+  brand, and detailed visual direction are primary review inputs.
 - \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
   into a prototype plan.
 - \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
@@ -1109,8 +1284,8 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`,
+\`/visual-questions\`) generate a plan and open the editor. Pass \`--no-connect\` to
 register the connector without authenticating, then run
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
@@ -1164,9 +1339,9 @@ and operate UI states, needs design review before code, wants comments pinned to
 live screens, or asks to move a visual plan into a prototype.
 
 Prefer \`/visual-plan\` for architecture, data flow, or non-interactive planning.
-Prefer \`/ui-plan\` when static screen review is enough. Use \`/visualize-plan\`
-first only when the user hands you an existing Markdown/Codex/Claude plan that
-needs a visual companion before becoming interactive.
+Prefer \`/ui-plan\` when static screen review is enough. Use \`/visual-plan\` first
+when the user hands you an existing Markdown/Codex/Claude plan that needs a
+visual companion before becoming interactive.
 
 ## Core Workflow
 
@@ -1290,9 +1465,117 @@ reviewing and iterating.
 
 - \`visual-plan\`
 - \`ui-plan\`
-- \`visualize-plan\`
 - \`visual-questions\`
 `;
+export const PLAN_DESIGN_SKILL_MD = `---
+name: plan-design
+description: >-
+  Use Agent-Native Plans for full-fidelity UI design planning with a Design
+  canvas tab and optional interactive Prototype tab before implementation.
+metadata:
+  visibility: exported
+---
+
+# Plan Design
+
+Use \`/plan-design\` when the user needs a high-fidelity product design before
+implementation: polished branded screens, realistic content, visual direction,
+and interaction review. It is the full-fidelity companion to \`/visual-plan\` and
+\`/prototype-plan\`: the top review surface should show \`Design\` and, when the
+flow needs interaction, \`Prototype\`.
+
+## When To Use
+
+Use this for UI-heavy work where brand, visual hierarchy, polished layout, or
+interaction feel are material to the decision. Skip it for small copy, spacing,
+or obvious component changes.
+
+## Research First
+
+Before creating the plan:
+
+1. Inspect the real app shell, routes, components, CSS variables, Tailwind
+   tokens, theme files, and any relevant screenshots.
+2. If \`design.md\` exists, treat it as the primary design brief and pass its
+   important content into \`create-plan-design.designMd\`.
+3. If a \`.fig\` local-copy file or parsed brand kit is available, use the
+   Design/brand-kit parsing actions from the app or shared tooling first, then
+   pass the extracted token summary into \`brandKit\`.
+4. Parse existing codebase style info when possible: CSS custom properties,
+   Tailwind config, global CSS, font declarations, spacing/radius tokens, and
+   component conventions. Pass the compact evidence into \`codebaseStyles\`.
+5. Ground every screen in actual product content. Avoid lorem ipsum, generic
+   marketing filler, and placeholder gray boxes unless designing an explicit
+   loading state.
+
+## Create The Plan
+
+Call \`create-plan-design\` with:
+
+- \`title\`, \`brief\`, \`repoPath\`, and any \`implementationNotes\`.
+- \`designMd\`, \`brandKit\`, \`codebaseStyles\`, or \`designNotes\` when available.
+- \`screens\`: one to six full-fidelity HTML/CSS screen fragments. Each screen
+  must include a bounded \`html\` fragment, optional scoped \`css\`, a \`surface\`,
+  and stable \`data-design-id\` attributes on elements a reviewer might edit.
+- \`transitions\` only when the Prototype tab should support true screen/step
+  navigation. Use \`data-goto="screen-id"\` in the screen HTML for those controls.
+
+The Design tab is the visual source of truth. The Prototype tab is for behavior
+and should reuse the same visual styling where practical. Do not create a
+separate design direction in the prototype.
+
+## Full-Fidelity HTML Rules
+
+- Write bounded fragments only: no \`<html>\`, \`<head>\`, \`<body>\`, \`<script>\`,
+  \`<style>\`, external imports, iframes, SVG, or executable URLs.
+- Put CSS in the screen \`css\` field. The renderer scopes it to the artboard.
+- Use real CSS and CSS variables. Tailwind-like class names are fine only when
+  the provided \`css\` defines them or the classes are harmless semantic hooks.
+- Use \`renderMode: "design"\` on design screen data when authoring full
+  structured content directly.
+- Add \`data-design-id="meaningful-name"\` to editable elements such as hero
+  panels, key buttons, cards, nav items, pricing rows, chart panels, and state
+  chips. Keep ids stable and descriptive.
+- Keep the design responsive within the selected surface. Text must not clip,
+  overlap, or rely on viewport-sized type.
+
+## Targeted Style Edits
+
+When a reviewer selects an element in the Design tab or asks for a specific
+style change, avoid regenerating the whole plan. Use:
+
+\`\`\`json
+{
+  "op": "update-design-element-style",
+  "frameId": "frame-overview",
+  "elementId": "primary-cta",
+  "styles": {
+    "background-color": "#0f766e",
+    "border-radius": "10px"
+  }
+}
+\`\`\`
+
+Use \`frameId\` for inline canvas designs or \`blockId\` for a referenced wireframe
+block. Set a style value to \`null\` to remove it. Use \`patch-wireframe-html\` or
+\`patch-prototype-html\` for text/content changes inside a fragment.
+
+## Document Handoff
+
+Below the visual surface, keep the document concise and implementation-oriented:
+actual files and symbols, state/actions/contracts, open questions, risks, and
+verification. The document should not repeat the same screens in prose.
+
+Before implementation, call \`get-plan-feedback\` and treat comments, selected
+element details, and recent review events as the source of truth.
+
+## Related Skills
+
+- \`visual-plan\`
+- \`ui-plan\`
+- \`prototype-plan\`
+- \`frontend-design\`
+`;
 export const VISUAL_QUESTIONS_SKILL_MD = `---
 name: visual-questions
 description: >-
@@ -1306,10 +1589,10 @@ metadata:
 # Visual Questions
 
 Use \`/visual-questions\` when the next best step is not a plan yet, but a
-reviewable visual intake: single-choice chips, multi-select chips, freeform
-notes, mockup choices, sketch diagrams, and a generated answer summary that feeds
-the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`,
-\`/prototype-plan\`, and \`/visualize-plan\`.
+reviewable visual intake: single-choice option rows, multi-select option rows,
+freeform notes, mockup choices, sketch diagrams, and a generated answer summary
+that feeds the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`,
+\`/prototype-plan\`, and \`/plan-design\`.
 
 ## When To Use
 
@@ -1320,11 +1603,11 @@ the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`,
   than answering text-only prompts.
 
 Gate hard: skip this for tiny, unambiguous changes. If the agent can reasonably
-infer the answer, prefer \`/ui-plan\`, \`/prototype-plan\`, or \`/visual-plan\` directly and put
-assumptions in the plan.
+infer the answer, prefer \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`, or
+\`/visual-plan\` directly and put assumptions in the plan.
 
 Visual questions are an explicit intake command, not an automatic preflight for
-\`/visual-plan\`, \`/ui-plan\`, or \`/prototype-plan\`.
+\`/visual-plan\`, \`/ui-plan\`, \`/prototype-plan\`, or \`/plan-design\`.
 
 ## Workflow
 
@@ -1335,9 +1618,10 @@ Visual questions are an explicit intake command, not an automatic preflight for
 3. Surface the returned Plans link and ask the user to answer visually.
 4. The generated summary drives the next step: \`create-ui-plan\` for static UI
    review, \`create-prototype-plan\` for click-through UI flows,
-   \`create-visual-plan\` for general plans, \`visualize-plan\` when a text plan
-   already exists, or \`update-visual-plan\` with targeted \`contentPatches\` to
-   fold answers into an active plan.
+   \`create-plan-design\` for high-fidelity branded UI review,
+   \`create-visual-plan\` for general plans or when a text plan already exists,
+   or \`update-visual-plan\` with targeted \`contentPatches\` to fold answers into
+   an active plan.
 5. If the user leaves comments, call \`get-plan-feedback\` before using the answers.
 
 ## Question Types
@@ -1374,8 +1658,11 @@ desktop/mobile pair for a popover, panel, or component.
 - \`create-ui-plan\`: create a UI-first plan from the answers.
 - \`create-prototype-plan\`: create a prototype-first plan from the answers when
   interaction feel matters.
-- \`create-visual-plan\`: create a general visual plan from the answers.
-- \`visualize-plan\`: enrich an existing text plan after answers are gathered.
+- \`create-plan-design\`: create a high-fidelity branded design plan from the
+  answers when visual polish is the primary review input.
+- \`create-visual-plan\`: create a general visual plan from the answers, or pass
+  existing plan text as \`planText\` when the answers should shape an imported
+  plan.
 - \`export-visual-plan\`: export answer plans as HTML, Markdown fallback,
   structured JSON, and MDX files when the intake needs to be checked into a repo.
 - \`read-visual-plan-source\` / \`patch-visual-plan-source\`: inspect or patch the
@@ -1394,456 +1681,8 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
-register the connector without authenticating, then run
-\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
-
-**Browser (people you share with).** Open the Plans editor and create & edit
-with no sign-up — you work as a guest. Sign in only when you want to save or
-share; signing in claims the plans you made as a guest into your account.
-
-Sharing and commenting require an account: public/shared plans are viewable by
-anyone with the link, but commenting on them needs an agent-native account.
-
-For fully offline, no-account use, run the Plans app locally and sync plans to
-your repo as MDX. This local mode is a separate advanced path, not the default
-hosted flow.
-
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. Authenticate the connector with
-\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
-instead re-run /mcp and choose Authenticate), then continue once the connector
-is available.
-
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
-not put shared secrets in skill files.
-`;
-export const VISUALIZE_PLAN_SKILL_MD = `---
-name: visualize-plan
-description: >-
-  Convert an existing Codex, Claude Code, Markdown, or pasted plan into an
-  Agent-Native Plans visual companion with diagrams, wireframes, prototypes,
-  annotations, and feedback.
-metadata:
-  visibility: exported
----
-
-# Visualize Plan
-
-Use \`/visualize-plan\` when a plan already exists and the user wants it easier to
-review. The native Codex or Claude Code plan can stay where it is; Agent-Native
-Plans creates a structured visual companion beside it — diagrams, wireframes,
-state sketches, functional prototypes, option cards, and comment prompts instead
-of a wall of text. It still reads like a plan, not a marketing page.
-
-Use \`/prototype-plan\` instead when the user wants a functional prototype as the first
-artifact and there is no text plan to preserve. When a text plan already exists,
-\`/visualize-plan\` should decide whether it needs no visual surface, canvas only,
-or canvas + prototype; call \`convert-visual-plan-to-prototype\` after
-visualization when its HTML wireframes should drive a prototype review.
-
-## Plan Discipline
-
-- **Gate hard.** A visual companion is worth it only when the source plan is
-  long, risky, or hard to react to as text. If the source plan is for trivial,
-  unambiguous work, skip the companion and just implement.
-- **Stay grounded and read-only.** Preserve the source plan's intent, do not
-  invent codebase facts, and label anything inferred as inferred. Make no source
-  edits while building or reviewing the companion.
-- **The companion is the approval gate.** Ask the user to review and approve the
-  direction before you write code, and name which files/areas the work touches.
-  Carry answerable unresolved assumptions and open questions into a bottom
-  \`question-form\` block instead of guessing silently.
-
-## Workflow
-
-1. Gather the existing plan text from the user's paste, a referenced file, or
-   recent visible agent context. Do not invent the source plan. If no plan text
-   exists and the work is UI-heavy, use \`/ui-plan\` or \`/prototype-plan\` instead.
-2. Call \`visualize-plan\` with \`planText\`, \`title\`, \`brief\`, \`source\`, and
-   \`repoPath\` when available.
-3. Surface the returned Plans link or inline MCP App.
-4. Decide the top visual surface with the rules below, then enrich the import
-   with \`update-visual-plan\` (prefer targeted \`contentPatches\`): add canvas
-   wireframes for user-visible UI, add \`content.prototype\` for multi-step flows,
-   add diagrams for architecture or data flow, add option cards for real
-   tradeoffs, and add explicit open questions. Apply the two cores below — the
-   companion must meet the same quality bar as a fresh plan, not be a thinner
-   ruleset. Label inferred visuals as inferred. When the user wants
-   source-control friendly edits, use \`patch-visual-plan-source\` against the MDX
-   files instead of regenerating the plan. If the user asks to make the visual
-   companion functional and the canvas contains HTML wireframes, call
-   \`convert-visual-plan-to-prototype\`.
-5. Ask the user to react, then call \`get-plan-feedback\` before implementing,
-   after review, and before the final response.
-6. Treat imported text as source material. The structured visual plan and
-   comments are the review surface; HTML is the export receipt. Do not replace a
-   native plan unless the user asks.
-
-## Visual Surface Choice
-
-Choose the surface after reading the source plan and before enriching it. Do not
-add visual chrome by default:
-
-- **No visual surface** when the imported plan is architecture-only,
-  backend-only, data migration, copy-only, or otherwise non-visual. Keep the
-  companion as a strong document and add diagrams only when relationships need a
-  visual explanation.
-- **Canvas only** when the source plan includes one static screen, a before/after
-  comparison, a component state, a small popover, or a visual direction that does
-  not require clicking. Put those wireframes in \`content.canvas\` and omit
-  \`content.prototype\`.
-- **Canvas + prototype** when the source plan describes a multi-step UI flow,
-  meaningful interactive app behavior, onboarding, wizard, review/approval flow,
-  navigation change, or any sequence the reviewer needs to operate. Keep the
-  static wireframes in
-  \`content.canvas\`, add the aligned functional prototype in
-  \`content.prototype\`, and rely on the top visual tabs to switch between them.
-- **Prototype-first conversion** when an already-visualized plan's HTML
-  wireframes should become functional. Use \`convert-visual-plan-to-prototype\` for
-  an existing canvas, or \`update-visual-plan\` with \`set-prototype\` when the
-  imported plan needs a hand-authored prototype that does not map cleanly from
-  the canvas. Keep static mocks unless the user explicitly asks to remove them.
-
-For mixed canvas + prototype companions, reuse the same real labels, states, and
-screen ids across both surfaces. The canvas is the inspectable static reference;
-the prototype is the interactive version of that same flow, not a separate
-design direction. If the imported plan only has text, add HTML wireframes before
-calling \`convert-visual-plan-to-prototype\`; never convert a diagram-only or
-empty canvas into a fake prototype.
-
-<!-- SHARED-CORE:wireframe-canvas START -->
-
-## Wireframe & Canvas Core
-
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for how wireframes and the
-canvas work. Do not paraphrase it per command.
-
-**A wireframe is an HTML mockup. The renderer owns the look; you write the
-content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
-screen and set \`data.surface\`. The renderer owns the surface footprint/aspect,
-the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
-never write \`<html>\`/\`<body>\`/\`<script>\`/\`<style>\` tags, font-family, hex colors,
-or any width/height/coordinates. You write real HTML layout and real product
-content; the renderer styles and roughens it.
-
-**A wireframe block's data is an HTML screen plus a surface:**
-
-\`\`\`json
-{
-  "surface": "browser",
-  "html": "<div style=\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\"><h1>Sign in</h1><p class=\\"wf-muted\\">Use your work email to continue.</p><div class=\\"wf-card\\" style=\\"display:flex;flex-direction:column;gap:10px\\"><label>Email<input value=\\"jane@acme.co\\" /></label><label>Password<input value=\\"••••••••\\" /></label><label style=\\"display:flex;align-items:center;gap:8px\\"><input type=\\"checkbox\\" checked /> Remember me</label><button class=\\"primary\\">Sign in</button></div><a href=\\"#\\">Forgot password?</a></div>"
-}
-\`\`\`
-
-**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
-(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
-are auto-themed — no classes needed. Helper classes carry the rest:
-
-- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
-- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
-  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
-- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
-- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
-  primary button.
-
-**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
-these on light/dark, so reading them is what keeps a mockup correct in both
-themes. For any inline border, background, or text color, reference a token:
-\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
-\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
-(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
-\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
-and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
-renderer owns the sketch/clean font.
-
-**Lay out with inline \`style\` flex/grid.** You write the real layout —
-\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
-renderer never repositions anything. Compose the actual product: reproduce the
-current screen, then show the modification. Real labels, real counts, real dates,
-real button text grounded in the screen you read; not lorem or gray bars.
-
-**Surface presets — match the real footprint, never default to desktop+mobile.**
-Pick the \`surface\` that matches what the user will actually see:
-
-- \`browser\`: a web page that needs a browser chrome frame around it.
-- \`desktop\`: a full desktop app page or app shell.
-- \`mobile\`: a phone screen, only when the work is genuinely mobile.
-- \`popover\`: a small floating menu, dropdown, or inline popover.
-- \`panel\`: a side panel, inspector, or sidebar widget.
-
-The surface locks the footprint and aspect; never set width/height/coordinates.
-A sidebar popover renders as a small surface, not a desktop page and a phone
-frame. Do not emit \`desktop\` + \`mobile\` variants unless responsive behavior
-actually changes the layout. For a component or widget, show one broader
-app-context frame only when placement affects understanding, then the focused
-component states.
-
-**Modify, don't redesign.** When the task changes an existing screen, reproduce
-the current screen's real layout and footprint FIRST, then change only the delta
-and call it out with a single annotation. Do not restack the page into a new
-layout. For net-new surfaces, compose from the real app shell.
-
-**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
-popover, menu, dialog, toast), show the full screen once, then add a small
-separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
-the whole page around it, and do not scale a duplicate up. Pick the matching
-\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
-page width.
-
-**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
-fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
-built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
-no labels or copy. The renderer drops borders, sketch, and color into the
-skeleton register automatically. Never escape to a \`custom-html\` document block
-to fake a loader, and never move a mockup out of the canvas — mockups always
-live in canvas artboards.
-
-**Editing an existing mockup.** To change one element, text, or color in an
-existing html mockup, do NOT regenerate the frame — call \`update-visual-plan\`
-with \`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
-replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
-first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
-occurrence. The result is re-sanitized.
-
-**Canvas annotations are designer notes on the artboard.** When a top canvas is
-present, sprinkle Figma-style notes near the frames they explain: a short
-heading, supporting text, and bullets — plain text layers, never bordered or
-shadowed cards, and never a box around a frame. The renderer spaces notes away
-from frames, so place each note by the frame it describes. Use an arrow only to
-point at one specific control or transition; for a broad frame-level note, write
-text beside the frame with no connector. Connectors are for real sequences only —
-never fake "Step 1 → Step 2" lines between independent states.
-
-**Do not create overlapping annotations.** Anchor each note to the frame it
-explains with \`targetId\` + \`placement\` (top/right/bottom/left). The renderer
-parks notes in a gutter beside the frame and lays them out automatically — never
-supply x/y or points for anchored notes; hand-placed coordinates fight the
-auto-layout and cause the overlap you're trying to avoid. Reserve arrows for a
-note that must point at a specific control inside a frame; a note that simply
-sits beside its frame needs no arrow.
-
-**Patching.** Edit one wireframe, canvas annotation, or block with targeted \`contentPatches\`
-(for example \`update-block\`, \`replace-blocks\`, \`update-canvas-annotation\`) rather
-than regenerating the whole plan. \`contentPatches\` are part of the public MCP
-action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
-edits. If an agent is working from exported source files, use
-\`read-visual-plan-source\` / \`patch-visual-plan-source\`: \`plan.mdx\` holds
-frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
-\`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
-patch action normalizes the MDX back into the same JSON runtime model. JSON is
-the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
-In the browser, humans edit \`rich-text\` prose inline; agents should still use
-\`update-rich-text\` content patches or source patches for prose, and use
-comments/structured patches for canvas, artboard, wireframe, and diagram edits.
-
-**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
-
-**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
-
-**Good example — a contacts list, surface \`browser\`.** A small, real screen
-composed from the helper classes and tokens, layout in inline flex, no fonts or
-hex colors:
-
-\`\`\`html
-<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
-  <div style="display:flex;align-items:center;justify-content:space-between">
-    <h1>Contacts</h1>
-    <button class="primary">New contact</button>
-  </div>
-  <div style="display:flex;gap:6px">
-    <span class="wf-pill accent">All 128</span>
-    <span class="wf-pill">Favorites</span>
-    <span class="wf-pill">Archived</span>
-  </div>
-  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
-    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
-      <span class="wf-pill">Lead</span>
-    </div>
-    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
-      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
-      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
-      <span class="wf-pill">Customer</span>
-    </div>
-  </div>
-</div>
-\`\`\`
-
-**Mockups belong in the top visual review area.** Static visuals live on the
-canvas; multi-step flows get both canvas wireframes and a prototype. When the
-user asks for a mockup, UI state, loading state, layout, screen, or visual
-comparison, make the canvas the primary home for that static visual. When the
-user asks for a prototype or the plan contains a sequence the reviewer must
-feel, keep the canvas artboards and add \`content.prototype\` so the top surface
-shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
-implementation, but they should not host the primary mockup or prototype just
-because \`custom-html\`, screenshots, or prose are easier to produce. If the
-canvas/prototype surface cannot represent the requested fidelity, still keep the
-closest top-surface representation and call out or extend the needed renderer
-capability.
-
-**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
-nodes instead of \`html\`; the renderer still accepts and displays it, but new
-plans emit \`html\`. Do not author fresh kit-tree screens — write the HTML mockup
-instead. Likewise, old or imported plans may carry coordinate-based regions or
-free-float x/y on notes or artboards; those are legacy escape hatches the
-renderer still shows but you must never produce. The \`surface\` drives the aspect
-and footprint, the canvas auto-places artboards, and the gutter parks notes by
-\`targetId\` + \`placement\`; never supply width, height, or coordinates for a new
-plan.
-
-<!-- SHARED-CORE:wireframe-canvas END -->
-
-<!-- SHARED-CORE:document-quality START -->
-
-## Document Quality Core
-
-This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`. It is the single source of truth for the document below the
-canvas. Do not paraphrase it per command.
-
-**The document is a serious technical plan, not marketing.** Write it the way a
-strong Claude or Codex implementation plan reads: outcome-first, prose-first,
-self-contained, and specific. State the objective and what "done" means, the
-scope and non-goals, the proposed approach with the key decisions and their
-rationale, ordered steps that name real files, symbols, actions, and data
-shapes, the risks, and a closing verification step (tests, build, or a checkable
-behavior). Replace vague prose with specifics; never ship a step like "make it
-work." No hero art, gradients, logos, nav bars, slogans, value props, giant
-landing-page headings, or marketing cards unless the user explicitly asks.
-
-**Top visuals and document never duplicate each other.** The UI story lives in
-the top visual surface: canvas artboards for static inspection, plus prototype
-tabs when the flow should be functional. The document carries the technical depth
-the visuals cannot show — concrete file/symbol maps, API and data contracts,
-code snippets, migration or implementation phases, risks, and validation. Repeat
-a wireframe in the document only for a genuinely new detail view or comparison.
-Skip the visual surface entirely for non-visual work and write a clean rich
-document.
-
-**Use the right block, and make it carry substance.** For the authoritative,
-machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
-— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
-so you never emit a block the editor cannot render or round-trip:
-
-- \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
-- \`implementation-map\` / \`code-tabs\` for the file map: file path, the
-  symbols/components to touch, the reason, risk/coordination notes, and a
-  concise syntax-highlighted snippet of the code shape — never the whole file,
-  never a prose-only file list.
-- \`decision\` for two or three option cards with consequences. These are static
-  records; do not style them like clickable tabs or chips unless the renderer
-  truly supports changing the selection.
-- \`diagram\` for architecture, sequence, data-flow, dependency, or state
-  relationships, only when it clarifies something real. Labels must not overlap
-  nodes, connectors, or each other.
-- \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
-  only prose usually means the plan is under-specified — include a relevant
-  visual unless the tab is intentionally document-only.
-- \`table\`, \`checklist\`, \`callout\` for scannable structure.
-
-**Open questions live at the bottom as a form when answers would change the
-plan.** Surface answerable unresolved decisions in a final \`question-form\`
-block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
-\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
-and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
-Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
-relevant section. Never bury a questions/decisions wall inside the plan
-narrative.
-
-**\`custom-html\` is a bounded escape hatch only** — a single complete fragment
-inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
-placeholder, density demo, or proof that custom HTML works. Prefer the native
-blocks for normal plans. It may support supplemental demos or references, but it
-is never the primary home for a requested mockup, UI state, or visual
-comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
-product fix is canvas support for that artifact type, not moving the mockup into
-the document.
-
-**Before handoff, open the plan and check it.** Fix overlap, excessive
-whitespace, clipped fragments, misleading inactive controls, poor contrast, and
-unreadable diagrams before asking for approval.
-
-<!-- SHARED-CORE:document-quality END -->
-
-<!-- SHARED-CORE:exemplar START -->
-
-## Good vs. Bad Exemplar
-
-**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard whose
-\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
-\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
-filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
-titles, due dates, and a primary \`button.primary\` — styled only through bare
-elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
-correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
-designer notes sit spaced off the frame, pointing only at the controls that need
-explanation. Below it, a Claude/Codex-grade document: objective and
-done-criteria, an \`implementation-map\` naming the real components and actions
-with short highlighted snippets, a \`decision\` card weighing two real approaches,
-and a validation step — none of it repeating the canvas. If the task also
-changes a multi-step completion flow, the same top area includes a Prototype tab
-whose screens use the same labels and states as the canvas artboards, with
-\`data-goto\` controls for the sequence. This is the bar.
-
-**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
-pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
-frame; a forced desktop + mobile pair for a popover; floating bordered
-annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
-instead of \`html\`; a multi-step UI flow with only static frames and no prototype
-tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
-document with a hero heading and value props that just restates what the canvas
-already shows. Never produce this.
-
-<!-- SHARED-CORE:exemplar END -->
-
-## Tool Guidance
-
-- \`visualize-plan\`: create the visual companion from the existing text plan.
-- \`update-visual-plan\`: enrich the import; prefer targeted \`contentPatches\` over
-  replacing the whole content. Use \`set-prototype\`, \`patch-prototype-html\`,
-  \`update-prototype-screen\`, and \`patch-wireframe-html\` when revising
-  functional prototype flows or their static frame counterparts.
-- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
-  into a functional prototype while preserving static mocks by default.
-- \`create-prototype-plan\`: use only when the user wants a prototype-first plan
-  and there is no existing plan text that \`/visualize-plan\` should preserve.
-- \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
-  optional \`canvas.mdx\`, optional \`prototype.mdx\`, optional \`.plan-state.json\`,
-  and JSON.
-- \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
-  artboard, annotation, component, prototype screen, or wireframe-node id.
-- \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
-- \`get-visual-plan\`: inspect the current structured plan, exported HTML, and
-  annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed reviewer comments before coding; it
-  returns grouped threads, exact anchor details, expected resolver, and recent
-  review-event payloads so agents can act only on the comments meant for them.
-- \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
-  files for repo check-in.
-
-When the user critiques a plan's look or structure, fix the renderer or this
-skill — never hand-edit one stored plan. Turn feedback into better guidance.
-
-## Setup & Authentication
-
-There are two ways into Plans.
-
-**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
-installs the Plans skills, registers the hosted Plans MCP connector, and
-authenticates it in the same step (a one-time browser sign-in at setup — this is
-intended), so the first tool call does not hit an OAuth wall:
-
-\`\`\`bash
-agent-native skills add visual-plan
-\`\`\`
-
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`,
+\`/visual-questions\`) generate a plan and open the editor. Pass \`--no-connect\` to
 register the connector without authenticating, then run
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
@@ -1960,13 +1799,13 @@ const BUILT_IN_APP_SKILLS = {
             "visual-questions": VISUAL_QUESTIONS_SKILL_MD,
             "ui-plan": UI_PLAN_SKILL_MD,
             "prototype-plan": PROTOTYPE_PLAN_SKILL_MD,
-            "visualize-plan": VISUALIZE_PLAN_SKILL_MD,
+            "plan-design": PLAN_DESIGN_SKILL_MD,
         },
         manifest: normalizeAppSkillManifest({
             schemaVersion: 1,
             id: "visual-plans",
             displayName: "Agent-Native Plans",
-            description: "Generate and review coding-agent plans as structured visual documents with diagrams, wireframes, prototypes, annotations, feedback, and HTML export.",
+            description: "Generate and review coding-agent plans as structured documents with inline diagrams, implementation maps, optional UI wireframes/prototypes, annotations, feedback, and HTML export.",
             hosted: {
                 url: "https://plan.agent-native.com",
                 mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
@@ -1974,13 +1813,14 @@ const BUILT_IN_APP_SKILLS = {
             mcp: { serverName: "agent-native-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add /visual-plan, /visual-questions, /ui-plan, /prototype-plan, and /visualize-plan skills plus the Plans MCP connector. Authenticate only for hosted/account-backed sharing.",
+                setup: "Install with the Agent-Native CLI to add the /visual-plan, /ui-plan, /prototype-plan, /plan-design, and /visual-questions skills plus the Plans MCP connector. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
                     id: "visual-plan",
                     action: "create-visual-plan",
                     path: "/plans",
+                    description: "Create a general coding-agent plan. Architecture/code plans default to inline document blocks; top canvas/prototype surfaces are optional for UI/product review.",
                 },
                 {
                     id: "visual-questions",
@@ -2001,9 +1841,10 @@ const BUILT_IN_APP_SKILLS = {
                     description: "Create a prototype-first Agent-Native plan with a functional live prototype above the document.",
                 },
                 {
-                    id: "visualize-plan",
-                    action: "visualize-plan",
+                    id: "plan-design",
+                    action: "create-plan-design",
                     path: "/plans",
+                    description: "Create a full-fidelity Agent-Native design plan with a Design canvas tab and optional matching Prototype tab.",
                 },
             ],
             skills: [
@@ -2028,9 +1869,9 @@ const BUILT_IN_APP_SKILLS = {
                     exportAs: "prototype-plan",
                 },
                 {
-                    path: "skills/visualize-plan",
+                    path: "skills/plan-design",
                     visibility: "exported",
-                    exportAs: "visualize-plan",
+                    exportAs: "plan-design",
                 },
             ],
             hostAdapters: [
@@ -2101,9 +1942,11 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "ui-plans": "visual-plans",
     "prototype-plan": "visual-plans",
     "prototype-plans": "visual-plans",
+    "plan-design": "visual-plans",
+    "plan-designs": "visual-plans",
+    "design-plan": "visual-plans",
+    "design-plans": "visual-plans",
     prototype: "visual-plans",
-    "visualize-plan": "visual-plans",
-    "visualize-plans": "visual-plans",
     "html-plan": "visual-plans",
     "plan-mode": "visual-plans",
     plannotate: "visual-plans",
@@ -2128,7 +1971,7 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
         "visual-questions",
         "ui-plan",
         "prototype-plan",
-        "visualize-plan",
+        "plan-design",
         "html-plan",
         "plannotate",
     ],