@agent-native/core 0.39.1 → 0.40.0

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|plan-design|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-recap|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:
@@ -195,8 +195,9 @@ iteration, or a human-in-the-loop choice among design directions.
   and token values. Never paste bearer tokens into chat or logs.
 `;
 /**
- * Shared setup/auth block for every Plans skill (`/visual-plan`, `/ui-plan`,
- * `/prototype-plan`, `/plan-design`, `/visual-questions`, `/visualize-plan`). Interpolated into each skill markdown
+ * Shared setup/auth block for every Plans skill (`/visual-plan`,
+ * `/visual-recap`, `/ui-plan`, `/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 +215,9 @@ 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\`, \`/plan-design\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/visual-recap\`, \`/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.
 
@@ -238,128 +240,21 @@ is available.
 
 Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
 not put shared secrets in skill files.`;
-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.
-metadata:
-  visibility: exported
----
-
-# Agent-Native Plans
-
-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.
-
-\`/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.
-
-## 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.
-
-## Plan Discipline
-
-- **Gate hard.** A polished visual plan is the most expensive plan form; only
-  invest when a wrong direction is costly. Skip it for trivial, unambiguous work
-  — typos, one-line fixes, a single well-specified function, anything whose diff
-  you could describe in one sentence — and just make the change. Never pad a plan
-  with filler and never ship a single-step plan.
-- **Research before you draft.** Read the real files, actions, schema, and
-  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.
-- **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
-  approach and options in the plan. Ask a clarifying question only when an
-  ambiguity would change the design and you cannot resolve it from the code; use
-  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
-  questions before finalizing. Do not call \`create-visual-questions\` from
-  \`/visual-plan\`; keep any answerable follow-up inside the plan itself as a
-  bottom \`question-form\` Open Questions block. Otherwise state the assumption
-  explicitly and proceed, and put anything unresolved in an open-questions block.
-- **The plan is the approval gate.** After surfacing it, ask the user to review
-  and approve before you write code, and name which files/areas the work touches.
-  Presenting the plan and requesting sign-off is the approval step — do not ask a
-  separate "does this look good?" question.
-- **The document is the source of truth, not the chat.** When scope shifts,
-  update the plan with \`update-visual-plan\` rather than only changing course in
-  chat, and re-read the approved plan before major steps.
-
-## Core Workflow
-
-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.
-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.
-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
-   of truth for exactly what changed and exactly what each comment points at.
-6. Apply changes with \`update-visual-plan\`, preferring targeted \`contentPatches\`.
-   When the user wants source-control friendly edits, use
-   \`patch-visual-plan-source\` against the MDX files instead of regenerating the
-   plan.
-7. Export with \`export-visual-plan\` only when the user wants a shareable receipt
-   or repo-check-in artifacts.
-
-## Visual Surface Choice
-
-Choose the surface before creating the 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.
-- **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\`.
-- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
-  review/approval flows, navigation changes, or anything where the reviewer
-  needs to operate the behavior. 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** when the user explicitly asks for \`/prototype-plan\`, asks
-  to operate the UI, or when interaction is the main question. Use
-  \`create-prototype-plan\`, which still preserves static mocks where useful.
-
-For mixed canvas + prototype plans, reuse the same real labels, app statuses,
-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.
-
-<!-- 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.
+// Single-source shared cores. Each partial is a heading-less BODY string that
+// begins and ends with its own SHARED-CORE marker comment, so the marker-region
+// sync guard can extract and compare it across the skills that consume it. The
+// skill constants below interpolate these partials at module-eval time; the
+// distributed artifact stays a flat string, so distribution is unchanged.
+//
+// Consumers:
+//   WIREFRAME_QUALITY_CORE  — visual-plan, ui-plan, visual-recap (surface-agnostic)
+//   CANVAS_SURFACE_CORE     — visual-plan, ui-plan (canvas/artboard mechanics)
+//   DOCUMENT_QUALITY_CORE   — visual-plan, ui-plan
+//   EXEMPLAR_CORE           — visual-plan, ui-plan
+// Surface-agnostic HTML wireframe quality rules. Applies equally to a standalone
+// WireframeBlock/<Screen> (visual-recap) and to a canvas artboard (visual-plan /
+// ui-plan). Do not put canvas/artboard placement mechanics here.
+const WIREFRAME_QUALITY_CORE = `<!-- SHARED-CORE:wireframe-quality START -->
 
 **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
@@ -414,18 +309,36 @@ Pick the \`surface\` that matches what the user will actually see:
 - \`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.
 
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve \`diagram\` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use \`surface: "popover"\` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching \`panel\` / \`desktop\` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+
 **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.
 
+**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
@@ -438,8 +351,7 @@ 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.
+to fake a loader.
 
 **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\`
@@ -448,47 +360,53 @@ 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.
+**Treat the wireframe border as part of the visible design.** Always wrap HTML
+wireframe content in a root container with real inner padding before drawing
+cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
+\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows so the
+first row never sits flush against the screen border. 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.
+
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+\`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+
+**Do not wrap intentionally single-line labels.** For tab rails, breadcrumbs,
+file chips, code filenames, and other deliberately single-line labels, do not
+let long text wrap. It is acceptable and usually preferable to use
+\`white-space: nowrap\`, \`overflow: hidden\`, and \`text-overflow: ellipsis\` (or
+abstract bars) so the wireframe demonstrates the actual layout behavior instead
+of producing ugly vertical text. Use horizontally scrollable or clipped rails
+for overflow.
 
 **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).
 
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new \`Edit with AI\` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half. Choose the
+before/after layout by geometry: use a \`columns\` block labeled \`Before\`/\`After\`
+when each state stays legible side by side; stack \`Before\` then \`After\`
+vertically in normal document flow when the surface is very wide, when
+full-width scanning matters, or when columns would shrink or crop the detail.
+Label each state visibly (for example, a header pill) so cropped screenshots
+stay unambiguous.
+
 **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;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>
@@ -498,53 +416,127 @@ 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.
+<!-- SHARED-CORE:wireframe-quality END -->`;
+// Canvas/artboard placement mechanics. Used only by visual-plan and ui-plan
+// (visual-recap renders standalone wireframes, not a canvas).
+const CANVAS_SURFACE_CORE = `<!-- SHARED-CORE:canvas-surface START -->
+
+**Artboard placement is locked by the \`surface\`, not by coordinates.** The
+surface locks the footprint and aspect; never set artboard width/height and
+never use coordinates inside the wireframe HTML. Let canvas auto-placement
+handle simple one-row boards. For mixed-footprint canvases, board-level artboard
+\`x\`/\`y\` is allowed and expected when it creates clear lanes.
+
+**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
+desktop frames plus compact \`mobile\`, \`popover\`, or \`panel\` surfaces, do not put
+everything in one horizontal strip. Use board-level artboard \`x\`/\`y\` to reserve
+lanes with generous empty space: main flow on one row, compact surfaces in their
+own column or row, and loading/error states in a lower row. Keep at least 96px
+between rendered artboard rectangles plus room for annotation gutters. Connect
+only neighboring steps; never draw a long connector that skips across unrelated
+frames. Before handoff, inspect the top canvas at default zoom and move any
+frame whose label, connector, or annotation crosses another frame.
 
-**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.
+**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.
 
-<!-- SHARED-CORE:wireframe-canvas END -->
+**Do not create overlapping annotations.** Anchor each ordinary note to the
+frame it explains with \`targetId\` + \`placement\` (top/right/bottom/left), and
+omit \`type\` or use \`type: "note"\`. The renderer parks notes in a gutter beside
+the frame and lays them out automatically. Do not use \`type: "callout"\`,
+\`type: "text"\`, \`type: "arrow"\`, x/y, or points for ordinary notes; those are
+freeform review-markup layers and must be reserved for intentional markup in
+open canvas space. Reserve arrows for a note that must point at one specific
+control inside a frame; a note that simply sits beside its frame needs no arrow.
+
+**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted \`contentPatches\`
+(for example \`patch-wireframe-html\`, \`patch-diagram-html\`, \`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.
 
-<!-- SHARED-CORE:document-quality START -->
+**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.
+
+**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. A skeleton/loading mockup
+also lives in a canvas artboard — never move a mockup out of the canvas.
 
-## Document Quality Core
+**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; those are legacy escape hatches the renderer still
+shows but you must never produce. The \`surface\` drives each artboard's aspect
+and footprint, and the gutter parks notes by \`targetId\` + \`placement\`. The only
+new-plan coordinate exception is deliberate board-level artboard \`x\`/\`y\` for
+multi-lane mixed-surface canvases; never supply artboard width/height, note
+coordinates, or wireframe-internal coordinates.
 
-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.
+<!-- SHARED-CORE:canvas-surface END -->`;
+const DOCUMENT_QUALITY_CORE = `<!-- SHARED-CORE:document-quality START -->
 
 **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,
@@ -556,14 +548,31 @@ 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. Leave room for the sketch font: keep
+labels short, give nodes generous width, and place boundary/annotation labels in
+unused space instead of over nodes. For small text/SVG changes to an existing
+HTML diagram, use \`patch-diagram-html\` with a unique \`find\`/\`replace\` snippet
+instead of resending the whole \`data.html\` string. 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\`
@@ -573,14 +582,33 @@ 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.
+- \`columns\` for side-by-side before/after or current/target comparisons where
+  each side needs real nested blocks; label the columns clearly and avoid
+  stacking comparison blocks vertically when parallel reading is the point.
+- \`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. Author diagram HTML with renderer-owned primitives
+  like \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
+  \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; they map to the plan's
+  Tailwind theme variables through \`--wf-ink\`, \`--wf-muted\`, \`--wf-line\`,
+  \`--wf-paper\`, \`--wf-card\`, \`--wf-accent\`, \`--wf-accent-soft\`, \`--wf-warn\`, and
+  \`--wf-ok\`, and switch to Virgil plus rough.js outlines in sketchy mode. Do not
+  set \`font-family\` and do not hard-code hex, rgb, or hsl colors in diagram HTML
+  or CSS. 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.
@@ -588,31 +616,31 @@ 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
 unreadable diagrams before asking for approval.
 
-<!-- SHARED-CORE:document-quality END -->
-
-<!-- SHARED-CORE:exemplar START -->
-
-## Good vs. Bad Exemplar
+<!-- SHARED-CORE:document-quality END -->`;
+const EXEMPLAR_CORE = `<!-- SHARED-CORE:exemplar START -->
 
 **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\`,
@@ -630,6 +658,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
@@ -637,14 +675,184 @@ 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 -->`;
+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 inline diagrams, implementation maps, optional UI/product
+  wireframes or prototypes, annotations, and comments.
+metadata:
+  visibility: exported
+---
+
+# Agent-Native Plans
+
+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: 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. 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 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
+
+- **Gate hard.** A polished visual plan is the most expensive plan form; only
+  invest when a wrong direction is costly. Skip it for trivial, unambiguous work
+  — typos, one-line fixes, a single well-specified function, anything whose diff
+  you could describe in one sentence — and just make the change. Never pad a plan
+  with filler and never ship a single-step plan.
+- **Research before you draft.** Read the real files, actions, schema, and
+  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
+  approach and options in the plan. Ask a clarifying question only when an
+  ambiguity would change the design and you cannot resolve it from the code; use
+  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
+  questions before finalizing. Do not call \`create-visual-questions\` from
+  \`/visual-plan\`; keep any answerable follow-up inside the plan itself as a
+  bottom \`question-form\` Open Questions block. Otherwise state the assumption
+  explicitly and proceed, and put anything unresolved in an open-questions block.
+- **The plan is the approval gate.** After surfacing it, ask the user to review
+  and approve before you write code, and name which files/areas the work touches.
+  Presenting the plan and requesting sign-off is the approval step — do not ask a
+  separate "does this look good?" question.
+- **The document is the source of truth, not the chat.** When scope shifts,
+  update the plan with \`update-visual-plan\` rather than only changing course in
+  chat, and re-read the approved plan before major steps.
+
+## Core Workflow
 
-<!-- SHARED-CORE:exemplar END -->
+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. 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\`, \`api-endpoint\`,
+   \`openapi-spec\`, \`data-model\`, \`diff\`, \`file-tree\`, \`json-explorer\`,
+   \`annotated-code\`,
+   \`implementation-map\` and \`code-tabs\` 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
+   of truth for exactly what changed and exactly what each comment points at.
+6. Apply changes with \`update-visual-plan\`, preferring targeted \`contentPatches\`.
+   When the user wants source-control friendly edits, use
+   \`patch-visual-plan-source\` against the MDX files instead of regenerating the
+   plan.
+7. Export with \`export-visual-plan\` only when the user wants a shareable receipt
+   or repo-check-in artifacts.
+
+## Visual Surface Choice
+
+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. 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\`.
+- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
+  review/approval flows, navigation changes, or anything where the reviewer
+  needs to operate the behavior. 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** when the user explicitly asks for \`/prototype-plan\`, asks
+  to operate the UI, or when interaction is the main question. Use
+  \`create-prototype-plan\`, which still preserves static mocks where useful.
+
+For mixed canvas + prototype plans, reuse the same real labels, app statuses,
+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.
+
+## Wireframe & Canvas Core
+
+This section is shared by \`/visual-plan\` and \`/ui-plan\`, and is the single
+source of truth for how wireframes and the canvas work. The wireframe-quality
+rules below are additionally shared, word for word, with \`/visual-recap\`; the
+canvas/artboard mechanics apply only to \`/visual-plan\` and \`/ui-plan\`. Do not
+paraphrase any of it per command.
+
+${WIREFRAME_QUALITY_CORE}
+
+${CANVAS_SURFACE_CORE}
+
+## Document Quality Core
+
+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.
+
+${DOCUMENT_QUALITY_CORE}
+
+## Good vs. Bad Exemplar
+
+${EXEMPLAR_CORE}
 
 ## 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.
@@ -654,7 +862,6 @@ already shows. Never produce this.
   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\`,
@@ -686,8 +893,9 @@ 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\`, \`/plan-design\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/visual-recap\`, \`/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.
 
@@ -732,8 +940,8 @@ react to.
 and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
 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, and \`/visualize-plan\`
-when a text plan already exists.
+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
 
@@ -773,305 +981,41 @@ when a text plan already exists.
    pause, and before the final response. Treat \`anchorDetails\`, resolver intent,
    recent review events, and any focused screenshots from browser handoff as the
    source of truth for exactly what changed and exactly what each UI comment
-   points at. Apply changes with \`update-visual-plan\`, preferring
-   \`contentPatches\` for one frame, annotation, node, tab, or block. When the
-   user wants source-control friendly edits, use \`patch-visual-plan-source\`
-   against the MDX files instead of regenerating the plan.
-
-## Agent Handoff
-
-After the canvas and document, add a short handoff that names the chosen UI
-direction, unresolved visual questions, and feedback that must be read before
-code changes. Never claim feedback has been applied until \`get-plan-feedback\` or
-the user has supplied it.
-
-<!-- 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.
+   points at. Apply changes with \`update-visual-plan\`, preferring
+   \`contentPatches\` for one frame, annotation, node, tab, or block. When the
+   user wants source-control friendly edits, use \`patch-visual-plan-source\`
+   against the MDX files instead of regenerating the plan.
 
-**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.
+## Agent Handoff
 
-**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.
+After the canvas and document, add a short handoff that names the chosen UI
+direction, unresolved visual questions, and feedback that must be read before
+code changes. Never claim feedback has been applied until \`get-plan-feedback\` or
+the user has supplied it.
 
-**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:
+## Wireframe & Canvas Core
 
-- \`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.
+This section is shared by \`/visual-plan\` and \`/ui-plan\`, and is the single
+source of truth for how wireframes and the canvas work. The wireframe-quality
+rules below are additionally shared, word for word, with \`/visual-recap\`; the
+canvas/artboard mechanics apply only to \`/visual-plan\` and \`/ui-plan\`. Do not
+paraphrase any of it per command.
 
-**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.
+${WIREFRAME_QUALITY_CORE}
 
-**\`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.
+${CANVAS_SURFACE_CORE}
 
-**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.
+## Document Quality Core
 
-<!-- SHARED-CORE:document-quality END -->
+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.
 
-<!-- SHARED-CORE:exemplar START -->
+${DOCUMENT_QUALITY_CORE}
 
 ## 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 -->
+${EXEMPLAR_CORE}
 
 ## Tool Guidance
 
@@ -1115,8 +1059,9 @@ 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\`, \`/plan-design\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/visual-recap\`, \`/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.
 
@@ -1170,9 +1115,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
 
@@ -1288,665 +1233,483 @@ Runtime JSON is canonical. Source export uses:
 - \`canvas.mdx\` for static mocks when a canvas is present
 - \`.plan-state.json\` for persisted viewport state
 
-Patch source with \`patch-visual-plan-source\` only when the user wants
-source-control friendly edits. Patch runtime content when the user is simply
-reviewing and iterating.
-
-## Related Skills
-
-- \`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`",
-].join("\n") + "\n";
-export const VISUAL_QUESTIONS_SKILL_MD = `---
-name: visual-questions
-description: >-
-  Use Agent-Native Plans to ask rich visual intake questions when
-  /visual-questions is explicitly requested before creating a UI plan or visual
-  plan.
-metadata:
-  visibility: both
----
-
-# 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\`, \`/plan-design\`, and \`/visualize-plan\`.
-
-## When To Use
-
-- The user asks to be shown options before the agent writes a plan.
-- UI direction, form factor, layout model, feature set, or visual style is fuzzy
-  enough that 2-6 answers would materially change the plan.
-- The user would benefit from choosing between visual mockups or diagrams rather
-  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\`, \`/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\`, \`/prototype-plan\`, or \`/plan-design\`.
-
-## Workflow
-
-1. Call \`create-visual-questions\` with a clear title, brief, source, and repo
-   path when known.
-2. Omit \`questions\` for the default UI intake. Provide a custom \`questions\` array
-   only when the task has domain-specific choices.
-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-plan-design\` for high-fidelity branded UI review,
-   \`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.
-5. If the user leaves comments, call \`get-plan-feedback\` before using the answers.
-
-## Question Types
-
-Supported \`questions\` entries:
-
-- \`single\`: chip group where one option wins.
-- \`multi\`: chip group where multiple options can be selected.
-- \`freeform\`: textarea for constraints, inspirations, or things to avoid.
-- \`visual\`: visual options with sketch previews — use for layout direction, flow
-  depth, surface choice, or diagram choices.
-
-Each option can include \`label\`, \`value\`, \`description\`, \`recommended\`,
-\`preview\`, and \`bullets\`. Valid \`preview\` values match the wireframe surfaces:
-\`desktop\`, \`mobile\`, \`popover\`, \`panel\`, \`component\`, \`split\`, \`flow\`, and
-\`diagram\`. Pick the preview that matches the real footprint — do not offer a
-desktop/mobile pair for a popover, panel, or component.
-
-## Quality Bar
-
-- Ask only decision-changing questions. A beautiful form with low-value questions
-  is still friction.
-- Prefer visible, answerable options over abstract prose.
-- Use visual tabs when users need to compare layout or flow shapes.
-- Keep the output calm and document-like, not a landing page.
-- The generated answer summary is not the final plan; it is the intake prompt for
-  the next agent step.
-
-## Tool Guidance
-
-- \`create-visual-questions\`: create the interactive intake plan.
-- \`get-visual-plan\`: inspect the current visual question plan.
-- \`get-plan-feedback\`: read comments before creating or updating the next plan.
-- \`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-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.
-- \`visualize-plan\`: enrich an existing text plan after answers are gathered.
-- \`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
-  MDX source if another agent is operating from checked-in plan files.
-
-## 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\`, \`/plan-design\`,
-\`/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.
+Patch source with \`patch-visual-plan-source\` only when the user wants
+source-control friendly edits. Patch runtime content when the user is simply
+reviewing and iterating.
 
-**Surface presets — match the real footprint, never default to desktop+mobile.**
-Pick the \`surface\` that matches what the user will actually see:
+## Related Skills
 
-- \`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.
+- \`visual-plan\`
+- \`ui-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
+---
 
-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.
+# Plan Design
 
-**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.
+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\`.
 
-**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.
+## When To Use
 
-**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.
+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:
 
-**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.
+\`\`\`json
+{
+  "op": "update-design-element-style",
+  "frameId": "frame-overview",
+  "elementId": "primary-cta",
+  "styles": {
+    "background-color": "#0f766e",
+    "border-radius": "10px"
+  }
+}
+\`\`\`
 
-**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.
+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.
 
-**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.
+## Document Handoff
 
-**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.
+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.
 
-**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.
+Before implementation, call \`get-plan-feedback\` and treat comments, selected
+element details, and recent review events as the source of truth.
 
-**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).
+## Related Skills
 
-**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:
+- \`visual-plan\`
+- \`ui-plan\`
+- \`prototype-plan\`
+- \`frontend-design\`
+`;
+export const VISUAL_RECAP_SKILL_MD = `---
+name: visual-recap
+description: >-
+  Use Agent-Native Plans to turn a code change, PR diff, or git diff into a
+  visual recap plan for high-altitude review — schema, API, file, and
+  before/after changes as grounded structured blocks instead of a wall of diff.
+metadata:
+  visibility: exported
+---
 
-\`\`\`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>
-\`\`\`
+# Visual Recap
 
-**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.
+\`/visual-recap\` creates a visual plan built **from** a diff, not toward one. It
+is the reverse of forward planning: instead of describing the change you are
+about to make, you describe the change that was just made, at a higher altitude
+than line-by-line review. The same plan data model serves both directions —
+schema, API, file, and architecture changes become the same \`data-model\`,
+\`api-endpoint\`, \`file-tree\`, and \`diagram\` blocks a forward plan would use, only
+now they summarize work that exists. A reviewer scans the shape of the change
+before spending attention on the literal lines.
 
-**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.
+## When To Use
 
-<!-- SHARED-CORE:wireframe-canvas END -->
+Build a recap when a PR or commit is large, multi-file, or touches schema, API
+contracts, or architecture, and a reviewer would benefit from seeing the change
+mapped to structured blocks before reading the raw diff. A GitHub Action can
+generate one automatically from a PR diff; an agent can generate one on request
+("recap this PR", "show me what this branch changed"). Skip it for small,
+single-file, or obvious diffs — a recap is review overhead, and a tiny change
+reviews faster as plain diff.
+
+## Recap The Whole Work Unit
+
+When \`/visual-recap\` is invoked in a chat thread after work has already happened,
+the default scope is the whole current work unit/thread, not only the most recent
+user message, tool action, or follow-up fix. Gather the thread-owned changes
+across the conversation: original implementation work, later bug fixes, UI
+follow-ups, tests, changesets, skill/instruction updates, generated plan/source
+artifacts, and any local import/linking fixes needed to make the recap open.
+
+Use the current diff plus conversation context to separate thread-owned changes
+from unrelated dirty work that existed before the thread. Exclude unrelated
+pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred,
+state the assumption or ask a concise question before publishing.
+
+When updating an existing recap after feedback, revise the recap so it still
+covers the whole thread/work unit plus the new correction. Do not replace a broad
+recap with a narrow recap of only the latest feedback unless the user explicitly
+asks for that narrower scope.
+
+## Keep The Recap Body Lean
+
+Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to
+the generated plan body. In particular, do not create a \`rich-text\` block just to
+say the recap is an aid, that the reviewer should still review the diff, how many
+files changed, or which ref/working tree generated the recap. The plan title,
+brief, \`file-tree\`, and optional \`diffstat\` already carry that context.
+
+Only add prose blocks when they tell the reviewer something specific about the
+change that the structured blocks do not: the objective, a real compatibility
+risk, an important decision visible in the diff, or a grounded review note.
+
+## UI Impact Needs Wireframes
+
+When the diff changes rendered UI, layout, density, visual state, interaction
+affordances, navigation, controls, menus, dialogs, or design tokens, the recap
+MUST include one or more wireframes. Prose and file diffs are not a substitute
+for showing what changed visually.
+
+Choose the smallest visual surface that makes the review clear:
+
+- Use a \`Before\` / \`After\` wireframe pair when the reviewer benefits from direct
+  comparison, such as a removed or added control, a changed state, layout
+  density, ordering, navigation, or a visible component replacement. The
+  Wireframe Quality core below owns how to lay that pair out (columns vs.
+  vertical stack by geometry).
+- Use an after-only wireframe when the change is purely additive or the "before"
+  state would only show absence without adding review value.
+- Use more than two wireframes when the UI change is flow-dependent, responsive,
+  or stateful; show the meaningful states in order instead of forcing a single
+  before/after pair.
+- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
+  matching \`surface\` (\`popover\`, \`panel\`, etc.) and show the focused sub-surface.
+  Do not redraw a full page unless placement in the page is itself part of the
+  change.
+
+Ground each wireframe in the changed UI behavior, component names, file paths,
+and diff-visible labels/states. If exact pixels are inferred rather than
+captured, say so in the wireframe caption or a concise annotation. For
+local/manual recaps, import or update the plan source that holds the wireframes
+so the rendered recap opens with the UI visual available.
+
+## Wireframe Quality
+
+UI recap wireframes must look like the UI surface that changed, not like generic
+architecture boxes. The following bar is shared, word for word, with
+\`/visual-plan\` and \`/ui-plan\`: it is the single source of truth for HTML
+wireframe quality, and applies to a recap's standalone \`wireframe\` /
+\`WireframeBlock\` / \`<Screen>\` exactly as it applies to a plan's canvas artboard.
+
+${WIREFRAME_QUALITY_CORE}
+
+Use the standard \`WireframeBlock\` / \`<Screen>\` format so the Plan viewer owns the
+surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate
+when placement precision matters, especially popovers, menus, dialogs, and dense
+forms; kit-tree wireframes are appropriate for simpler layouts. For HTML
+wireframes, keep \`renderMode\` unset or \`wireframe\` unless a design-only editable
+mockup is explicitly required, because \`renderMode="design"\` disables the
+sketchy rough overlay.
+
+Before sharing a UI-impact recap, render it in the Plan viewer and inspect it at
+the current theme. If any label, annotation, toolbar, or wireframe content
+overlaps another element, fix the MDX and re-import before reporting the link. A
+text-match screenshot is not enough; visually inspect the captured image.
+
+## Open And Report The Recap
+
+After creating the recap, link the reviewer to the rendered plan with an
+**absolute URL**. Never make the primary link a local \`plan.mdx\` file, a local
+mirror folder, or a relative path such as \`/plans/<id>\`.
+
+Resolve the URL in this order:
+
+1. When creating a recap for local edits and a running local/dev Plan app origin
+   is known, prefer that local origin even if \`plan.mdx\` includes a hosted
+   \`visualUrl\`, e.g. \`http://localhost:8081/plans/<id>\`.
+2. Use the absolute \`visualUrl\` exported in \`plan.mdx\` frontmatter when present,
+   e.g. \`https://plan.agent-native.com/plans/<id>\`.
+3. If the action returns only a relative \`url\`/\`path\` and the running app origin
+   is known, construct an absolute URL from that origin, e.g.
+   \`http://localhost:5173/plans/<id>\`.
+4. If only the plan id is available, build the hosted absolute URL
+   \`https://plan.agent-native.com/plans/<id>\` and say if that URL was inferred.
+
+When running in Codex and the Browser/in-app side browser tools are available,
+open the absolute recap URL there automatically after creation. Still include the
+same absolute URL in the final response. Local mirror files like
+\`plans/<slug>/plan.mdx\` may be mentioned only as secondary source-control
+artifacts, not as the main way to open the recap.
+
+## Diff → Block Mapping
+
+Map each kind of change to the block that carries it, derived mechanically from
+the actual diff:
+
+- **Schema / migration change** → \`data-model\` for the resulting entities,
+  fields, and relations, plus a \`diff\` with \`mode: "split"\` for the literal SQL
+  or schema text that changed. The \`data-model\` shows the new shape; the split
+  \`diff\` shows exactly what moved.
+- **API / action / route change** → \`api-endpoint\` with the method, path,
+  params, request, and responses as they are after the change. Mark removed
+  endpoints with \`deprecated: true\` and explain in prose.
+  Keep multiple API endpoints in the normal single-column document flow unless
+  they are an explicit before/after contract comparison.
+- **Compatibility-sensitive change** → short \`rich-text\` notes beside the
+  relevant \`data-model\` / \`api-endpoint\` block. Name the changed field,
+  endpoint, or behavior and mark whether it is breaking, risky, or non-breaking;
+  pair that note with a split \`diff\` for the literal lines.
+- **Any meaningful code hunk** → \`diff\` with \`mode: "split"\`, carrying the real
+  \`before\` / \`after\` text and the \`filename\` / \`language\`. Split mode is the
+  default for a recap because before/after legibility is the whole point.
+  When several key files each need a substantial diff, group those \`diff\` blocks
+  in a reusable \`tabs\` block with \`orientation: "vertical"\` so file labels form a
+  left rail and the selected file's split diff renders on the right. Keep each
+  tab label to the file path or a short basename plus directory hint.
+  If the recap ends with more than one supporting diff, that trailing diff
+  appendix should be one vertical \`tabs\` block, not a stack of separate \`diff\`
+  blocks.
+- **Files added / removed / renamed** → \`file-tree\` with each entry's \`change\`
+  flag (\`added\`, \`removed\`, \`modified\`, \`renamed\`) and a short \`note\`; attach a
+  \`snippet\` only when one tells the reviewer something the path does not.
+- **Rendered UI / interaction change** → one or more wireframes showing the
+  visible UI delta before the reviewer reads code. Use \`Before\` / \`After\`
+  wireframes when the comparison clarifies the change; otherwise use after-only
+  or a short state/flow sequence. Use realistic UI surfaces: for a popover
+  change, show a popover with its title row, top-right actions, options/fields,
+  and any opened prompt/menu anchored to the correct trigger. Keep the body lean:
+  the wireframe carries the UI story, while the file tree and split \`diff\`
+  blocks carry implementation evidence.
+- **Architecture or data-flow shift** → \`diagram\` with \`data.html\` / \`data.css\`
+  as a two-panel before/after, layered, or swimlane layout, or \`mermaid\` for a
+  quick graph. Use the two-dimensional layouts the Document Quality core
+  prescribes; do not reduce a structural change to a left-to-right chain.
+  Do not use \`diagram\` as a stand-in for rendered UI controls; UI changes need
+  \`wireframe\` blocks.
+  Diagram HTML/CSS should use renderer-owned primitives such as
+  \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
+  \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; these map to the plan's
+  Tailwind theme variables through \`--wf-ink\`, \`--wf-muted\`, \`--wf-line\`,
+  \`--wf-paper\`, \`--wf-card\`, \`--wf-accent\`, \`--wf-accent-soft\`, \`--wf-warn\`, and
+  \`--wf-ok\`, and switch to Virgil plus rough.js outlines in sketchy mode. Do not
+  set \`font-family\` and do not emit hex, rgb/hsl literals, or one-off dark/light
+  palettes in diagram CSS.
+- **Outcome-first narrative** → \`rich-text\` for the "what changed and why" prose:
+  the objective the diff served, the key decisions visible in it, and the risks a
+  reviewer should weigh. This is the only place the model writes freely.
+
+## Before / After Is The Headline
+
+The recap's center of gravity is the before/after comparison. For document-body
+comparisons there are two primitives, and they cover the whole need together:
+
+- **\`columns\`** — the side-by-side container, for **structured** comparisons.
+  Use two columns labeled \`Before\` and \`After\`, each holding a block (commonly a
+  \`data-model\`, \`api-endpoint\`, or \`rich-text\`), so the reviewer reads the old
+  shape against the new shape in one glance. This is the right primitive for
+  "the schema went from X to Y" or "the endpoint contract changed like this."
+  Do not use \`columns\` simply to compact or group a list of API endpoints.
+- **\`diff\` with \`mode: "split"\`** — for **code**. The split renders the literal
+  removed and added lines side by side. Use it for the actual hunks.
+
+For UI diffs, wireframes are the visual comparison primitive. Use before/after
+wireframes when the comparison clarifies the change; use after-only or a state
+sequence when that better matches the change. The visual headline must show
+exact placement, realistic chrome, and adequate padding before any abstract
+explanation. The Wireframe Quality core owns the before/after layout choice
+(side-by-side \`columns\` vs. vertical stack, picked by geometry); never
+hand-build a side-by-side wireframe layout in \`custom-html\`. For document-body
+comparisons, there is no other multi-column primitive — \`columns\` plus split
+\`diff\` are the whole comparison vocabulary. Do not hand-build side-by-side
+layouts in \`custom-html\`, and do not stack two \`data-model\` blocks vertically
+and call it a comparison when \`columns\` exists to put them side by side.
+
+## Grounding Rule
+
+Structured blocks are **true by construction** only if they are derived from the
+actual changed lines. The \`diff\`, \`data-model\`, \`api-endpoint\`, and \`file-tree\`
+blocks MUST be built mechanically from the real diff — real paths, real fields,
+real method/path, real before/after text — never inferred, rounded, or invented.
+The model writes only the prose: the "why", the narrative, the risk read. A
+confidently wrong recap is dangerous in a review context, because a reviewer who
+trusts the summary may skip the very line the summary got wrong. When the diff
+does not contain a fact, leave it out rather than guess; mark anything the model
+inferred (not extracted) as inferred in prose.
+
+## Security
+
+- **Gate visibility.** Recaps of a private repo are org/login-gated — set the
+  plan's visibility to the owning org or login, never auto-public. A recap can
+  expose unreleased schema, internal endpoints, and architecture; treat it like
+  the source it summarizes.
+- **Never transcribe secrets.** A diff can contain API keys, tokens, webhook
+  URLs, signing secrets, \`.env\` values, or credential-looking literals. Do not
+  copy any of these into a \`diff\`, \`file-tree\` snippet, \`api-endpoint\`, or prose
+  block — redact them (\`sk-•••\`, \`<redacted>\`). This mirrors the repo's
+  hardcoded-secret rule: obviously fake placeholders only, never the real value,
+  in any block, caption, or note.
+
+## Bidirectional Loop (Fast-Follow)
+
+Because a recap is a real, editable plan, the same review loop as forward plans
+applies: a reviewer can annotate any block, and the coding agent reads
+\`get-plan-feedback\` to drive fixes back into the code — annotation → agent →
+diff, the same close-the-loop flow forward plans use. In v1, recaps are
+**read-only**: they summarize a merged or proposed change for review, and the
+annotate-to-fix loop is a fast-follow, not yet wired. Build the recap so the
+blocks are anchorable and the loop drops in later without restructuring.
 
-<!-- SHARED-CORE:document-quality START -->
+## Related Skills
 
-## Document Quality Core
+- **visual-plan** — the canonical command and the source of the shared Wireframe
+  & Canvas and Document Quality cores; a recap follows the same block discipline
+  in reverse.
+- **security** — data scoping, secret handling, and the hardcoded-secret rule the
+  recap's redaction and visibility gating mirror.
+- **sharing** — org/login-gated visibility for the plan that holds the recap.
+`;
+export const VISUAL_QUESTIONS_SKILL_MD = `---
+name: visual-questions
+description: >-
+  Use Agent-Native Plans to ask rich visual intake questions when
+  /visual-questions is explicitly requested before creating a UI plan or visual
+  plan.
+metadata:
+  visibility: both
+---
 
-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.
+# Visual Questions
 
-**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.
+Use \`/visual-questions\` when the next best step is not a plan yet, but a
+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\`.
 
-**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 To Use
 
-**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:
+- The user asks to be shown options before the agent writes a plan.
+- UI direction, form factor, layout model, feature set, or visual style is fuzzy
+  enough that 2-6 answers would materially change the plan.
+- The user would benefit from choosing between visual mockups or diagrams rather
+  than answering text-only prompts.
 
-- \`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.
+Gate hard: skip this for tiny, unambiguous changes. If the agent can reasonably
+infer the answer, prefer \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`, or
+\`/visual-plan\` directly and put assumptions in the plan.
 
-**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.
+Visual questions are an explicit intake command, not an automatic preflight for
+\`/visual-plan\`, \`/ui-plan\`, \`/prototype-plan\`, or \`/plan-design\`.
 
-**\`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.
+## Workflow
 
-**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.
+1. Call \`create-visual-questions\` with a clear title, brief, source, and repo
+   path when known.
+2. Omit \`questions\` for the default UI intake. Provide a custom \`questions\` array
+   only when the task has domain-specific choices.
+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-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.
 
-<!-- SHARED-CORE:document-quality END -->
+## Question Types
 
-<!-- SHARED-CORE:exemplar START -->
+Supported \`questions\` entries:
 
-## Good vs. Bad Exemplar
+- \`single\`: chip group where one option wins.
+- \`multi\`: chip group where multiple options can be selected.
+- \`freeform\`: textarea for constraints, inspirations, or things to avoid.
+- \`visual\`: visual options with sketch previews — use for layout direction, flow
+  depth, surface choice, or diagram choices.
 
-**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.
+Each option can include \`label\`, \`value\`, \`description\`, \`recommended\`,
+\`preview\`, and \`bullets\`. Valid \`preview\` values match the wireframe surfaces:
+\`desktop\`, \`mobile\`, \`popover\`, \`panel\`, \`component\`, \`split\`, \`flow\`, and
+\`diagram\`. Pick the preview that matches the real footprint — do not offer a
+desktop/mobile pair for a popover, panel, or component.
 
-**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.
+## Quality Bar
 
-<!-- SHARED-CORE:exemplar END -->
+- Ask only decision-changing questions. A beautiful form with low-value questions
+  is still friction.
+- Prefer visible, answerable options over abstract prose.
+- Use visual tabs when users need to compare layout or flow shapes.
+- Keep the output calm and document-like, not a landing page.
+- The generated answer summary is not the final plan; it is the intake prompt for
+  the next agent step.
 
 ## 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.
+- \`create-visual-questions\`: create the interactive intake plan.
+- \`get-visual-plan\`: inspect the current visual question plan.
+- \`get-plan-feedback\`: read comments before creating or updating the next plan.
+- \`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-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
+  MDX source if another agent is operating from checked-in plan files.
 
 ## Setup & Authentication
 
@@ -1961,8 +1724,9 @@ 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\`, \`/plan-design\`,
-\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+After that, \`/visual-plan\` (and \`/visual-recap\`, \`/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.
 
@@ -2076,17 +1840,17 @@ const BUILT_IN_APP_SKILLS = {
     "visual-plans": {
         skillName: "visual-plan",
         extraSkills: {
+            "visual-recap": VISUAL_RECAP_SKILL_MD,
             "visual-questions": VISUAL_QUESTIONS_SKILL_MD,
             "ui-plan": UI_PLAN_SKILL_MD,
             "prototype-plan": PROTOTYPE_PLAN_SKILL_MD,
             "plan-design": PLAN_DESIGN_SKILL_MD,
-            "visualize-plan": VISUALIZE_PLAN_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",
@@ -2094,13 +1858,20 @@ const BUILT_IN_APP_SKILLS = {
             mcp: { serverName: "agent-native-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add the /visual-plan, /ui-plan, /prototype-plan, /plan-design, /visual-questions, 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, /visual-recap, /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-recap",
+                    action: "create-visual-recap",
+                    path: "/plans",
+                    description: "Create a visual recap plan from a PR, commit, branch, or git diff for high-altitude review.",
                 },
                 {
                     id: "visual-questions",
@@ -2126,11 +1897,6 @@ const BUILT_IN_APP_SKILLS = {
                     path: "/plans",
                     description: "Create a full-fidelity Agent-Native design plan with a Design canvas tab and optional matching Prototype tab.",
                 },
-                {
-                    id: "visualize-plan",
-                    action: "visualize-plan",
-                    path: "/plans",
-                },
             ],
             skills: [
                 {
@@ -2138,6 +1904,11 @@ const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "visual-plan",
                 },
+                {
+                    path: "skills/visual-recap",
+                    visibility: "exported",
+                    exportAs: "visual-recap",
+                },
                 {
                     path: "skills/visual-questions",
                     visibility: "exported",
@@ -2158,11 +1929,6 @@ const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "plan-design",
                 },
-                {
-                    path: "skills/visualize-plan",
-                    visibility: "exported",
-                    exportAs: "visualize-plan",
-                },
             ],
             hostAdapters: [
                 "codex-plugin",
@@ -2226,6 +1992,10 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "agent-native-design-exploration": "design",
     "visual-plans": "visual-plans",
     "visual-plan": "visual-plans",
+    "visual-recap": "visual-plans",
+    "visual-recaps": "visual-plans",
+    "code-review-recap": "visual-plans",
+    "code-review-recaps": "visual-plans",
     "visual-questions": "visual-plans",
     "visual-question": "visual-plans",
     "ui-plan": "visual-plans",
@@ -2237,8 +2007,6 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "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",
@@ -2260,11 +2028,12 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     ],
     "visual-plans": [
         "visual-plan",
+        "visual-recap",
+        "code-review-recap",
         "visual-questions",
         "ui-plan",
         "prototype-plan",
         "plan-design",
-        "visualize-plan",
         "html-plan",
         "plannotate",
     ],