@agent-native/core 0.39.2 → 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|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`). 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\`) 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,155 +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 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
-
-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\`, \`data-model\`, \`file-tree\`,
-   \`implementation-map\`, \`code-tabs\`, and \`annotated-code\` blocks directly next
-   to the relevant prose. Skip the top visual surface for non-visual work.
-4. Surface the returned Plans link or inline MCP App and ask the user to review.
-   Always include the actual URL in chat so the next step is a click in CLI or
-   other text-only hosts. When the host exposes an embedded browser/preview panel
-   and a tool can open arbitrary URLs there, open the returned plan URL
-   automatically for convenient review; do not rely on this as the only handoff.
-   Treat that browser open as a convenience and smoke test, not as the access
-   model. Plans should load out of the box for the local agent and local browser
-   session; if a signed-in embedded browser cannot read a local plan that an
-   anonymous/tool check can read, fix the app/action ownership or access path
-   rather than patching one plan by hand.
-5. Call \`get-plan-feedback\` before editing, after review, after any long pause,
-   and before the final response. Treat \`anchorDetails\`, resolver intent, recent
-   review events, and any focused screenshots from browser handoff as the source
-   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.
-
-<!-- SHARED-CORE:wireframe-canvas START -->
-
-## Wireframe & Canvas Core
-
-This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
-the single source of truth for how wireframes and the canvas work. Do not
-paraphrase it per command.
+// 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
@@ -441,13 +309,22 @@ 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
@@ -474,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\`
@@ -484,49 +360,45 @@ 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\`; 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.
+**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:
@@ -572,6 +444,70 @@ hex colors:
 </div>
 \`\`\`
 
+<!-- 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.
+
+**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 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.
+
+**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,
@@ -585,27 +521,22 @@ 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.
+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.
 
 **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
+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
+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\` and \`/ui-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,
@@ -631,13 +562,17 @@ swimlanes, dependency maps, matrices, or grouped regions. Do not default to
 left-to-right chains; use a line only when the relationship is truly a sequence.
 Use native \`diagram\` blocks with \`data.html\` / \`data.css\` for these richer
 layouts; the fragment may use semantic HTML and inline SVG, and the renderer
-applies the viewer's sketch/clean style. Legacy \`nodes\` / \`edges\` are only for
-tiny previews or genuinely linear step flows. Repeat a wireframe in the document
-only for a genuinely new detail view or comparison. Skip the visual surface
-entirely for non-visual work and write a clean rich document. For a simple
-binary UI visual choice, show the two directions in the canvas only; do not
-repeat the same options as body wireframes, a \`decision\` block, or prose. Put
-the actual choice in the bottom "Open Questions" form.
+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\`
@@ -654,16 +589,26 @@ so you never emit a block the editor cannot render or round-trip:
 - \`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.
+- \`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. 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.
+  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.
@@ -694,11 +639,8 @@ for that artifact type, not moving the mockup into the document.
 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\`,
@@ -737,510 +679,343 @@ 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 -->
+<!-- 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
+---
 
-## Tool Guidance
+# Agent-Native Plans
 
-- \`create-visual-plan\`: start one structured visual plan per agent task/run, or
-  import an existing text plan by passing \`planText\`; \`content\` may include no
-  visual surface, canvas only, or canvas + prototype.
-- \`create-ui-plan\`: start a UI-first plan when the work is primarily product UI.
-- \`create-prototype-plan\`: start a prototype-first plan with a functional top
-  review surface.
-- \`create-plan-design\`: start a full-fidelity branded Design-tab plan with an
-  optional matching Prototype tab.
-- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
-  into a prototype plan.
-- \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
-  command, not as \`/visual-plan\` preflight.
-- \`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\`,
-  optional \`canvas.mdx\`, optional \`.plan-state.json\`, and JSON.
-- \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
-  artboard, annotation, component, or wireframe-node id.
-- \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
-- \`get-visual-plan\`: read the current structured plan, exported HTML, and
-  annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently; it
-  returns grouped threads, exact anchor details, expected resolver, and recent
-  review-event payloads so agents can act only on the comments meant for them.
-- \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
-  files for repo check-in.
-
-When the user critiques a plan's look or structure, fix the renderer or this
-skill — never hand-edit one stored plan. Turn feedback into better guidance.
-
-## Setup & Authentication
-
-There are two ways into Plans.
-
-**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
-installs the Plans skills, registers the hosted Plans MCP connector, and
-authenticates it in the same step (a one-time browser sign-in at setup — this is
-intended), so the first tool call does not hit an OAuth wall:
-
-\`\`\`bash
-agent-native skills add visual-plan
-\`\`\`
-
-After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`, \`/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.
-
-**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 UI_PLAN_SKILL_MD = `---
-name: ui-plan
-description: >-
-  Use Agent-Native Plans for UI-first planning with an optional top pan/zoom
-  wireframe canvas, a refined Notion-like document, rich tabs, diagrams,
-  comments, drawing, and agent handoff.
-metadata:
-  visibility: exported
----
+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.
 
-# UI Plan
+\`/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.
 
-Use \`/ui-plan\` when the task is primarily about product UI, user flows,
-interaction details, component layout, or visual direction. The reviewable UI
-comes first; implementation detail comes after the user has something concrete to
-react to.
+## When To Use
 
-\`/visual-plan\` remains the general command for architecture, backend, refactors,
-and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
-prototype instead of static screens. Use \`/plan-design\` when polish, brand, or
-visual fidelity are material to the decision. Use \`/visual-questions\` only when
-the user explicitly wants visual intake before planning. Use \`/visual-plan\` when
-a text plan already exists and should become the source material for the review.
+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.** Use a UI plan when the surface is new, ambiguous, spans several
-  screens or states, or the direction needs agreement before coding. Skip it for
-  cosmetic one-liners — a color, a label, a spacing tweak — and just make the
-  change. Never ship a single-step or filler plan.
-- **Research before you draft.** Read the real components, routes, and design
-  tokens first; ground every mockup and the file map in actual files and symbols.
-  Delegate wide exploration to a sub-agent when the surface is large.
-- **Planning is read-only.** Make no source edits while building or reviewing.
-  Start editing only after the user approves the UI direction.
-- **Clarify vs. assume.** Do not ask how to build the UI — present the direction
-  and options as mockups and tabs. Ask a clarifying question only when an
-  ambiguity would change the design; use the host agent's normal
-  ask-user-question flow and batch 2-4 before finalizing. Do not call
-  \`create-visual-questions\` from \`/ui-plan\`; keep answerable follow-up inside
-  the same plan as a bottom \`question-form\` Open Questions block. Otherwise
-  state the assumption in the plan and proceed.
-- **The plan is the approval gate.** Ask the user to review and approve the UI
-  direction before you write code, and name the files/areas the work touches.
-
-## UI-First Workflow
-
-1. Follow the host agent's normal planning flow: inspect the codebase, gather
-   the UI/component context needed, and ask native clarifying questions as needed
-   before generating the plan.
-2. Call \`create-ui-plan\` with a UI-specific title, brief, source, repo path, and
-   structured \`content\`. The canvas comes first, the document second.
-3. Compose the top canvas from the kit (see the cores below): the key artboards
-   with real product content, designer notes, and connectors only for real
-   sequences. Skip the canvas when wireframes would not clarify the work.
-4. Continue below as a concise technical document that stays close to the
-   Markdown plan the agent would normally output — not a second copy of the
-   canvas — covering concrete files, contracts, phases, risks, and validation.
-5. Call \`get-plan-feedback\` before implementation, after review, after a 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 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\` and \`/ui-plan\`. It is
-the single source of truth for how wireframes and the canvas work. Do not
-paraphrase it per command.
-
-**A wireframe is an HTML mockup. The renderer owns the look; you write the
-content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
-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.
+- **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.
 
-**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.
+## Core Workflow
 
-**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.
+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.
 
-**Surface presets — match the real footprint, never default to desktop+mobile.**
-Pick the \`surface\` that matches what the user will actually see:
+## Visual Surface Choice
 
-- \`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.
+Choose the surface before creating the plan or after reading the source plan. Do
+not add visual chrome by default:
 
-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.
+- **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.
 
-**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.
+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.
 
-**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.
+## Wireframe & Canvas Core
 
-**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.
+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.
 
-**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.
+${WIREFRAME_QUALITY_CORE}
 
-**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_SURFACE_CORE}
 
-**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.
+## Document Quality Core
 
-**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.
+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.
 
-**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.
+${DOCUMENT_QUALITY_CORE}
 
-**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.
+## Good vs. Bad Exemplar
 
-**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).
+${EXEMPLAR_CORE}
 
-**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:
+## Tool Guidance
 
-\`\`\`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>
+- \`create-visual-plan\`: start one structured visual plan per agent task/run, or
+  import an existing text plan by passing \`planText\`; \`content\` may include no
+  visual surface, canvas only, or canvas + prototype.
+- \`create-ui-plan\`: start a UI-first plan when the work is primarily product UI.
+- \`create-prototype-plan\`: start a prototype-first plan with a functional top
+  review surface.
+- \`create-plan-design\`: start a full-fidelity branded Design-tab plan with an
+  optional matching Prototype tab.
+- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
+  into a prototype plan.
+- \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
+  command, not as \`/visual-plan\` preflight.
+- \`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\`,
+  optional \`canvas.mdx\`, optional \`.plan-state.json\`, and JSON.
+- \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
+  artboard, annotation, component, or wireframe-node id.
+- \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
+- \`get-visual-plan\`: read the current structured plan, exported HTML, and
+  annotations; it also returns the MDX folder for source workflows.
+- \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently; it
+  returns grouped threads, exact anchor details, expected resolver, and recent
+  review-event payloads so agents can act only on the comments meant for them.
+- \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
+  files for repo check-in.
+
+When the user critiques a plan's look or structure, fix the renderer or this
+skill — never hand-edit one stored plan. Turn feedback into better guidance.
+
+## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and
+authenticates it in the same step (a one-time browser sign-in at setup — this is
+intended), so the first tool call does not hit an OAuth wall:
+
+\`\`\`bash
+agent-native skills add visual-plan
 \`\`\`
 
-**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.
+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.
 
-**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.
+**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.
 
-<!-- SHARED-CORE:wireframe-canvas END -->
+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.
 
-<!-- SHARED-CORE:document-quality START -->
+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.
 
-## Document Quality Core
+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.
 
-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.
+Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
+not put shared secrets in skill files.
+`;
+export const UI_PLAN_SKILL_MD = `---
+name: ui-plan
+description: >-
+  Use Agent-Native Plans for UI-first planning with an optional top pan/zoom
+  wireframe canvas, a refined Notion-like document, rich tabs, diagrams,
+  comments, drawing, and agent handoff.
+metadata:
+  visibility: exported
+---
 
-**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.
+# UI Plan
 
-**When top visuals exist, they and the document never duplicate each other.**
-For UI work, the UI story lives in the top visual surface: canvas artboards for
-static inspection, plus prototype tabs when the flow should be functional. The
-document carries the technical depth the visuals cannot show — concrete
-file/symbol maps, API and data contracts, code snippets, migration or
-implementation phases, risks, and validation. For architecture/code reviews,
-invert that: the document is the visual surface, and each recommendation should
-carry its own nearby inline \`diagram\` / \`data-model\` block plus file evidence
-and terse Problem/Solution/Why text. For architecture/code diagrams, prefer
-standard two-dimensional layouts: paired before/after panels, layered diagrams,
-swimlanes, dependency maps, matrices, or grouped regions. Do not default to
-left-to-right chains; use a line only when the relationship is truly a sequence.
-Use native \`diagram\` blocks with \`data.html\` / \`data.css\` for these richer
-layouts; the fragment may use semantic HTML and inline SVG, and the renderer
-applies the viewer's sketch/clean style. Legacy \`nodes\` / \`edges\` are only for
-tiny previews or genuinely linear step flows. Repeat a wireframe in the document
-only for a genuinely new detail view or comparison. Skip the visual surface
-entirely for non-visual work and write a clean rich document. For a simple
-binary UI visual choice, show the two directions in the canvas only; do not
-repeat the same options as body wireframes, a \`decision\` block, or prose. Put
-the actual choice in the bottom "Open Questions" form.
+Use \`/ui-plan\` when the task is primarily about product UI, user flows,
+interaction details, component layout, or visual direction. The reviewable UI
+comes first; implementation detail comes after the user has something concrete to
+react to.
 
-**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:
+\`/visual-plan\` remains the general command for architecture, backend, refactors,
+and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
+prototype instead of static screens. Use \`/plan-design\` when polish, brand, or
+visual fidelity are material to the decision. Use \`/visual-questions\` only when
+the user explicitly wants visual intake before planning. Use \`/visual-plan\` when
+a text plan already exists and should become the source material for the review.
 
-- \`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 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 two-dimensional architecture, dependency, data-flow, or state
-  relationships, only when it clarifies something real. For architecture/code
-  diagrams, prefer \`data.html\` / \`data.css\` with semantic HTML and inline SVG so
-  the diagram can use panels, layers, matrices, arrows, annotations, and
-  responsive layout directly. Use legacy \`nodes\` / \`edges\` only for small
-  previews or truly sequential flows. In architecture/code plans, prefer a
-  repeated section rhythm: recommendation title, confidence and category badges,
-  code-path evidence, a local before/after or current/target spatial diagram,
-  then concise Problem/Solution/Why text. Labels must not overlap nodes,
-  connectors, or each other.
-- \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
-  only prose usually means the plan is under-specified — include a relevant
-  visual unless the tab is intentionally document-only.
-- \`table\`, \`checklist\`, \`callout\` for scannable structure.
+## Plan Discipline
 
-**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" 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\`.
+- **Gate hard.** Use a UI plan when the surface is new, ambiguous, spans several
+  screens or states, or the direction needs agreement before coding. Skip it for
+  cosmetic one-liners — a color, a label, a spacing tweak — and just make the
+  change. Never ship a single-step or filler plan.
+- **Research before you draft.** Read the real components, routes, and design
+  tokens first; ground every mockup and the file map in actual files and symbols.
+  Delegate wide exploration to a sub-agent when the surface is large.
+- **Planning is read-only.** Make no source edits while building or reviewing.
+  Start editing only after the user approves the UI direction.
+- **Clarify vs. assume.** Do not ask how to build the UI — present the direction
+  and options as mockups and tabs. Ask a clarifying question only when an
+  ambiguity would change the design; use the host agent's normal
+  ask-user-question flow and batch 2-4 before finalizing. Do not call
+  \`create-visual-questions\` from \`/ui-plan\`; keep answerable follow-up inside
+  the same plan as a bottom \`question-form\` Open Questions block. Otherwise
+  state the assumption in the plan and proceed.
+- **The plan is the approval gate.** Ask the user to review and approve the UI
+  direction before you write code, and name the files/areas the work touches.
 
-**\`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. 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.
+## UI-First 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. Follow the host agent's normal planning flow: inspect the codebase, gather
+   the UI/component context needed, and ask native clarifying questions as needed
+   before generating the plan.
+2. Call \`create-ui-plan\` with a UI-specific title, brief, source, repo path, and
+   structured \`content\`. The canvas comes first, the document second.
+3. Compose the top canvas from the kit (see the cores below): the key artboards
+   with real product content, designer notes, and connectors only for real
+   sequences. Skip the canvas when wireframes would not clarify the work.
+4. Continue below as a concise technical document that stays close to the
+   Markdown plan the agent would normally output — not a second copy of the
+   canvas — covering concrete files, contracts, phases, risks, and validation.
+5. Call \`get-plan-feedback\` before implementation, after review, after a 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 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:document-quality END -->
+## Wireframe & Canvas Core
 
-<!-- SHARED-CORE:exemplar START -->
+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.
 
-## Good vs. Bad Exemplar
+${WIREFRAME_QUALITY_CORE}
 
-**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.
+${CANVAS_SURFACE_CORE}
 
-**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.
+## Document Quality Core
 
-**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. 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.
+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
 
-<!-- SHARED-CORE:exemplar END -->
+${EXEMPLAR_CORE}
 
 ## Tool Guidance
 
@@ -1284,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\`) 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.
 
@@ -1576,6 +1352,273 @@ element details, and recent review events as the source of truth.
 - \`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
+---
+
+# Visual Recap
+
+\`/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.
+
+## When To Use
+
+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.
+
+## Related Skills
+
+- **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: >-
@@ -1681,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\`) 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.
 
@@ -1796,6 +1840,7 @@ 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,
@@ -1813,7 +1858,7 @@ 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, and /visual-questions 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: [
                 {
@@ -1822,6 +1867,12 @@ const BUILT_IN_APP_SKILLS = {
                     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",
                     action: "create-visual-questions",
@@ -1853,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",
@@ -1936,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",
@@ -1968,6 +2028,8 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     ],
     "visual-plans": [
         "visual-plan",
+        "visual-recap",
+        "code-review-recap",
         "visual-questions",
         "ui-plan",
         "prototype-plan",