@agent-native/core 0.37.3 → 0.39.0

package/dist/cli/skills.js

@@ -8,30 +8,39 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { buildAppSkillPack, ensureAppSkill, loadAppSkillManifest, normalizeAppSkillManifest, } from "./app-skill.js";
-import { readConnectClientPreferences, resolveClients, writeConnectClientPreferences, } from "./connect.js";
+import { readConnectClientPreferences, resolveClients, runConnect, writeConnectClientPreferences, } from "./connect.js";
 import { CONTEXT_XRAY_SKILL_MD, installLocalContextXray, } from "./context-xray-local.js";
 import { CLIENTS } from "./mcp-config-writers.js";
 const HELP = `agent-native skills
 
 Usage:
   agent-native skills list
-  agent-native skills add assets|design-exploration|visual-plan|visual-questions|ui-plan|visualize-plan|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--yes] [--dry-run] [--json]
+  agent-native skills add assets|design-exploration|visual-plan|visual-questions|ui-plan|prototype-plan|visualize-plan|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--yes] [--dry-run] [--json]
   agent-native skills add <manifest-or-app-dir> [--client ...] [--yes]
 
 Examples:
   agent-native skills add assets
   agent-native skills add design-exploration
   agent-native skills add visual-plan
+  agent-native skills add visual-plan --no-connect
   agent-native skills add context-xray --client all
   agent-native skills add assets --client claude-code
   agent-native skills add assets --mcp-url https://my-app.ngrok-free.dev
   agent-native skills add ./dist/assets-skill --client codex
 
-The add command wraps the Vercel Labs/open skills CLI for SKILL.md
-installation, then registers the app-backed MCP connector. Running
-"npx skills add ..." directly installs instructions only; use this Agent Native
-CLI path when you want MCP setup too. Pass --mcp-url to register that connector
-against a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
+The add command installs the SKILL.md instructions, registers the app-backed
+MCP connector, and then authenticates it in one step so you do not hit an OAuth
+wall on the first tool call. Authentication reuses "agent-native connect":
+OAuth-capable clients (Claude Code) get a URL-only entry and a /mcp authenticate
+prompt, while Codex / Cowork run the browser device-code flow. In a
+non-interactive shell or CI the auth step is skipped and the exact
+"agent-native connect <url>" command is printed instead.
+
+Running "npx skills add ..." directly installs instructions only; use this Agent
+Native CLI path when you want MCP setup and auth too. Pass --no-connect to
+register the connector without authenticating (leave auth to the host or run
+"agent-native connect" later). Pass --mcp-url to register that connector against
+a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
 deployment) instead of the built-in hosted default — a bare origin gets the
 standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
 bundles and custom adapter output.`;
@@ -185,6 +194,50 @@ iteration, or a human-in-the-loop choice among design directions.
 - If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
   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`, `/visual-questions`, `/visualize-plan`). 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).
+ */
+const PLAN_SETUP_AUTH_MD = `## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and
+authenticates it in the same step (a one-time browser sign-in at setup — this is
+intended), so the first tool call does not hit an OAuth wall:
+
+\`\`\`bash
+agent-native skills add visual-plan
+\`\`\`
+
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
+\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+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 VISUAL_PLANS_SKILL_MD = `---
 name: visual-plan
 description: >-
@@ -199,15 +252,16 @@ metadata:
 
 Agent-Native Plans is structured visual planning mode for coding agents. Build
 the plan you would normally write in Markdown, but as a scannable document with
-editable blocks mixed in: an optional pan/zoom wireframe canvas on top and a
-Notion-like technical document below. The user reacts to visuals first and reads
-prose only where it helps.
+editable blocks mixed in: an optional top visual review area (wireframe canvas,
+live prototype, or both in tabs) and a Notion-like technical document below. The
+user reacts to visuals first and reads prose only where it helps.
 
 \`/visual-plan\` is the canonical command and the main entry point. Use \`/ui-plan\`
 when the work is primarily product UI and review should start with the screens.
-Use \`/visual-questions\` to run a visual intake form first. Use \`/visualize-plan\`
-to turn an existing Codex, Claude Code, Markdown, or pasted plan into a visual
-companion.
+Use \`/prototype-plan\` when review should start with a functional live prototype.
+Use \`/visual-questions\` only when the user explicitly wants a visual intake form
+before planning. Use \`/visualize-plan\` to turn an existing Codex, Claude Code,
+Markdown, or pasted plan into a visual companion.
 
 ## When To Use
 
@@ -231,8 +285,11 @@ direction before you implement.
   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; batch
-  2-4 high-leverage questions before finalizing. Otherwise state the assumption
+  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.
@@ -244,102 +301,151 @@ direction before you implement.
 
 ## Core Workflow
 
-1. Call \`create-visual-plan\` with the title, brief, source, repo path, and
-   structured \`content\` blocks.
-2. Compose the canvas from the kit and write the document with native blocks
-   (see the two cores below). Skip the canvas for non-visual work.
-3. Surface the returned Plans link or inline MCP App and ask the user to review.
-4. Call \`get-plan-feedback\` before editing, after review, after any long pause,
-   and before the final response.
-5. Apply changes with \`update-visual-plan\`, preferring targeted \`contentPatches\`.
+1. Follow the host agent's normal planning flow: inspect the codebase, delegate
+   wide exploration when useful, gather the info needed, and ask native
+   clarifying questions as needed before generating the plan.
+2. Decide the top visual surface with the rules below, then call
+   \`create-visual-plan\` with the title, brief, source, repo path, and structured \`content\` blocks.
+3. Compose any top visual surface from the kit and write the document with
+   native blocks (see the cores below). Keep the document close to the Markdown
+   plan the agent would normally output; add diagrams, wireframes, prototypes,
+   and visual callouts only where they clarify the plan. Skip the top visual
+   surface for non-visual work.
+4. Surface the returned Plans link or inline MCP App and ask the user to review.
+   Always include the actual URL in chat so the next step is a click in CLI or
+   other text-only hosts. When the host exposes an embedded browser/preview panel
+   and a tool can open arbitrary URLs there, open the returned plan URL
+   automatically for convenient review; do not rely on this as the only handoff.
+5. Call \`get-plan-feedback\` before editing, after review, after any long pause,
+   and before the final response. Treat \`anchorDetails\`, resolver intent, recent
+   review events, and any focused screenshots from browser handoff as the source
+   of truth for exactly what changed and exactly what each comment points at.
+6. Apply changes with \`update-visual-plan\`, preferring targeted \`contentPatches\`.
    When the user wants source-control friendly edits, use
    \`patch-visual-plan-source\` against the MDX files instead of regenerating the
    plan.
-6. Export with \`export-visual-plan\` only when the user wants a shareable receipt
+7. Export with \`export-visual-plan\` only when the user wants a shareable receipt
    or repo-check-in artifacts.
 
+## Visual Surface Choice
+
+Choose the surface before creating the plan. Do not add visual chrome by
+default:
+
+- **No visual surface** for architecture-only, backend-only, data migration,
+  copy-only, or otherwise non-visual plans. Use a strong document with diagrams
+  only when relationships need a visual explanation.
+- **Canvas only** for one static screen, a before/after comparison, a component
+  state, a small popover, or a visual direction that does not require clicking.
+  Put those wireframes in \`content.canvas\` and omit \`content.prototype\`.
+- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
+  review/approval flows, navigation changes, or anything where the reviewer
+  needs to operate the behavior. Keep the static wireframes in
+  \`content.canvas\`, add the aligned functional prototype in
+  \`content.prototype\`, and rely on the top visual tabs to switch between them.
+- **Prototype-first** when the user explicitly asks for \`/prototype-plan\`, asks
+  to operate the UI, or when interaction is the main question. Use
+  \`create-prototype-plan\`, which still preserves static mocks where useful.
+
+For mixed canvas + prototype plans, reuse the same real labels, app statuses,
+and screen ids across both surfaces. The canvas is the inspectable static reference;
+the prototype is the interactive version of that same flow, not a separate
+design direction.
+
 <!-- SHARED-CORE:wireframe-canvas START -->
+
 ## Wireframe & Canvas Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
 \`/visualize-plan\`. It is the single source of truth for how wireframes and the
 canvas work. Do not paraphrase it per command.
 
-**The renderer owns all visual quality. You emit content, never styling.** Flex
-layout, fonts, density, spacing, theme, and the hand-drawn wobble all live in
-the app renderer. Never emit coordinates, CSS, pixel sizes, or raw HTML for a
-wireframe's internals. Your job is to pick a surface, compose real product
-content from the kit, and annotate — nothing else.
+**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 a declarative kit tree, not geometry:**
+**A wireframe block's data is an HTML screen plus a surface:**
 
 \`\`\`json
 {
-  "surface": "desktop",
-  "screen": [
-    { "el": "browserBar", "title": "tasklist" },
-    { "el": "row", "children": [
-      { "el": "sidebar", "children": [
-        { "el": "navItem", "label": "Inbox", "count": 12, "active": true },
-        { "el": "navItem", "label": "Today", "count": 4 },
-        { "el": "navItem", "label": "Done" }
-      ] },
-      { "el": "main", "children": [
-        { "el": "title", "text": "Today", "script": true },
-        { "el": "chips", "items": [
-          { "label": "All", "active": true }, { "label": "Active" }, { "label": "Done" }
-        ] },
-        { "el": "section", "label": "OVERDUE", "tone": "warn" },
-        { "el": "taskRow", "title": "Send invoice to Acme Co.", "due": "Yesterday", "dueTone": "warn", "prio": 1 },
-        { "el": "taskRow", "title": "Reply to design feedback", "due": "Today", "prio": 2 }
-      ] }
-    ] }
-  ]
+  "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>"
 }
 \`\`\`
 
-The renderer maps each node to a flex kit component and applies one whole-frame
-wobble. Layout is always flex: \`row\`, \`col\`, \`sidebar\`, and \`main\` set the flex
-direction; everything aligns by construction, so you never get overlap or drift.
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
+- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
+  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
+- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
+- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
+  primary button.
+
+**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
+\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
+(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
+\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
+and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
+renderer owns the sketch/clean font.
+
+**Lay out with inline \`style\` flex/grid.** You write the real layout —
+\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
 
 **Surface presets — match the real footprint, never default to desktop+mobile.**
 Pick the \`surface\` that matches what the user will actually see:
 
-- \`desktop\`: a full page or app shell.
+- \`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.
-- \`browser\`: a page that needs a browser chrome frame around it.
 
+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.
 
-**Node vocabulary (\`el\` values).** Every node is \`{ el, ...props, children? }\`:
-
-- Layout: \`screen\`, \`row\`, \`col\`, \`sidebar\`, \`main\`, \`card{children}\`,
-  \`column{title,count?,children}\`, \`box{children,dashed?}\`, \`divider\`.
-- Chrome: \`browserBar{title}\`, \`statusBar\`, \`searchBar\`, \`toolbar\`.
-- Navigation: \`navItem{label,count?,active?,dot?}\`, \`tabs\`/\`chips{items:[{label,active?}]}\`,
-  \`chip{label,active?}\`, \`pill{label,tone?}\`.
-- Content: \`title{text,script?}\`, \`text{value,color?,weight?}\`,
-  \`lines{n?,widths?}\`, \`section{label,tone?}\`,
-  \`taskRow{title,note?,due?,dueTone?,prio?,done?}\`, \`kv{rows:[{k,v}]}\`,
-  \`avatar\`, \`iconSquare{active?}\`.
-- Inputs: \`field{label?,value?,placeholder?,area?}\`, \`check{done?,shape?}\`,
-  \`btn{label,solid?,full?}\`, \`fab{icon?}\`.
-
-Put **real product content** in props: real labels, real dates, real counts,
-real button text grounded in the actual screen or component you read. Use
-\`lines\`/\`text\` (with no \`value\`) only for genuine placeholder body copy — never
-fill a screen with gray placeholder bars. Buttons (\`btn\`, \`fab\`) must read as
-actionable controls.
-
-**Default crisp.** Sketchiness is a low default (a subtle single wobble over the
-whole frame), not a heavy scribble. Do not ask for or assume a heavy sketch
-look.
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
+fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
+built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a \`custom-html\` document block
+to fake a loader, and never move a mockup out of the canvas — mockups always
+live in canvas artboards.
+
+**Editing an existing mockup.** To change one element, text, or color in an
+existing html mockup, do NOT regenerate the frame — call \`update-visual-plan\`
+with \`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
+first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
+occurrence. The result is re-sanitized.
 
 **Canvas annotations are designer notes on the artboard.** When a top canvas is
 present, sprinkle Figma-style notes near the frames they explain: a short
@@ -350,8 +456,16 @@ 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.
 
-**Patching.** Edit one wireframe node, canvas annotation, or block with targeted \`contentPatches\`
-(for example \`update-wireframe-node\`, \`update-block\`, \`replace-blocks\`) rather
+**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
@@ -360,14 +474,71 @@ frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
 \`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
 patch action normalizes the MDX back into the same JSON runtime model. JSON is
 the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit \`rich-text\` prose inline; agents should still use
+\`update-rich-text\` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Good example — a contacts list, surface \`browser\`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+\`\`\`html
+<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+\`\`\`
+
+**Mockups belong in the top visual review area.** Static visuals live on the
+canvas; multi-step flows get both canvas wireframes and a prototype. When the
+user asks for a mockup, UI state, loading state, layout, screen, or visual
+comparison, make the canvas the primary home for that static visual. When the
+user asks for a prototype or the plan contains a sequence the reviewer must
+feel, keep the canvas artboards and add \`content.prototype\` so the top surface
+shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
+implementation, but they should not host the primary mockup or prototype just
+because \`custom-html\`, screenshots, or prose are easier to produce. If the
+canvas/prototype surface cannot represent the requested fidelity, still keep the
+closest top-surface representation and call out or extend the needed renderer
+capability.
+
+**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
+nodes instead of \`html\`; the renderer still accepts and displays it, but new
+plans emit \`html\`. Do not author fresh kit-tree screens — write the HTML mockup
+instead. Likewise, old or imported plans may carry coordinate-based regions or
+free-float x/y on notes or artboards; those are legacy escape hatches the
+renderer still shows but you must never produce. The \`surface\` drives the aspect
+and footprint, the canvas auto-places artboards, and the gutter parks notes by
+\`targetId\` + \`placement\`; never supply width, height, or coordinates for a new
+plan.
 
-**Legacy imports only.** Old or imported plans may carry coordinate-based
-regions or a full standalone HTML document; the renderer still displays them.
-Never emit geometry, regions, or a standalone HTML document for a new plan —
-compose the kit tree instead.
 <!-- SHARED-CORE:wireframe-canvas END -->
 
 <!-- SHARED-CORE:document-quality START -->
+
 ## Document Quality Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
@@ -384,14 +555,19 @@ 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.
 
-**Canvas and document never duplicate each other.** The UI story lives on the
-canvas with on-canvas annotations; the document carries the technical depth the
-canvas cannot show — concrete file/symbol maps, API and data contracts, code
-snippets, migration or implementation phases, risks, and validation. Repeat a
-wireframe in the document only for a genuinely new detail view or comparison.
-Skip the canvas entirely for non-visual work and write a clean rich document.
+**Top visuals and document never duplicate each other.** The UI story lives in
+the top visual surface: canvas artboards for static inspection, plus prototype
+tabs when the flow should be functional. The document carries the technical depth
+the visuals cannot show — concrete file/symbol maps, API and data contracts,
+code snippets, migration or implementation phases, risks, and validation. Repeat
+a wireframe in the document only for a genuinely new detail view or comparison.
+Skip the visual surface entirely for non-visual work and write a clean rich
+document.
 
-**Use the right block, and make it carry substance:**
+**Use the right block, and make it carry substance.** For the authoritative,
+machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
+— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
+so you never emit a block the editor cannot render or round-trip:
 
 - \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
 - \`implementation-map\` / \`code-tabs\` for the file map: file path, the
@@ -409,46 +585,72 @@ Skip the canvas entirely for non-visual work and write a clean rich document.
   visual unless the tab is intentionally document-only.
 - \`table\`, \`checklist\`, \`callout\` for scannable structure.
 
-**Open questions are callouts, not buried prose.** Surface anything unresolved in
-a dedicated open-questions / needs-clarification block. Never put a
-questions/decisions wall inside the plan narrative.
+**Open questions live at the bottom as a form when answers would change the
+plan.** Surface answerable unresolved decisions in a final \`question-form\`
+block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
+\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
+and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
+Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
+relevant section. Never bury a questions/decisions wall inside the plan
+narrative.
 
 **\`custom-html\` is a bounded escape hatch only** — a single complete fragment
-inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a placeholder,
-density demo, or proof that custom HTML works. Prefer the native blocks; they
-cover real plans.
+inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
+placeholder, density demo, or proof that custom HTML works. Prefer the native
+blocks for normal plans. It may support supplemental demos or references, but it
+is never the primary home for a requested mockup, UI state, or visual
+comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
+product fix is canvas support for that artifact type, not moving the mockup into
+the document.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
 unreadable diagrams before asking for approval.
+
 <!-- SHARED-CORE:document-quality END -->
 
 <!-- SHARED-CORE:exemplar START -->
+
 ## Good vs. Bad Exemplar
 
-**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard
-composed from the kit — a sidebar of real \`navItem\`s (\`Inbox 12\`, \`Today 4\`,
-\`Done\`), a \`main\` with a scripted \`title\`, real \`chips\`, a \`section\` labeled
-\`OVERDUE\`, and \`taskRow\`s carrying real titles, due dates, and priorities — one
-subtle whole-frame wobble, correct desktop footprint, and plain-text designer
-notes spaced off the frames 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. This is the bar.
-
-**BAD.** Empty coordinate boxes placed by \`x/y/width/height\`, gray placeholder
-bars "insinuating" text, crisp double-bordered rectangles or a heavy scribble, a
-forced desktop + mobile pair for a popover, floating bordered annotation cards
-hugging the frames, and a marketing-style document with a hero heading and value
-props that just restates what the canvas already shows. Never produce this.
+**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard whose
+\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
+\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
+filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
+titles, due dates, and a primary \`button.primary\` — styled only through bare
+elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, an \`implementation-map\` naming the real components and actions
+with short highlighted snippets, a \`decision\` card weighing two real approaches,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+\`data-goto\` controls for the sequence. This is the bar.
+
+**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
+instead of \`html\`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Never produce this.
+
 <!-- SHARED-CORE:exemplar END -->
 
 ## Tool Guidance
 
-- \`create-visual-plan\`: start one structured visual plan per agent task/run.
+- \`create-visual-plan\`: start one structured visual plan per agent task/run;
+  \`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-visual-questions\`: run a visual intake form before planning.
+- \`create-prototype-plan\`: start a prototype-first plan with a functional top
+  review surface.
+- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
+  into a prototype plan.
+- \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
+  command, not as \`/visual-plan\` preflight.
 - \`visualize-plan\`: build a visual companion from an existing text plan.
 - \`update-visual-plan\`: revise content, status, or comments; prefer
   \`contentPatches\` over regenerating the whole plan.
@@ -459,13 +661,50 @@ props that just restates what the canvas already shows. Never produce this.
 - \`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.
+- \`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\`,
+\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+register the connector without authenticating, then run
+\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
+
+**Browser (people you share with).** Open the Plans editor and create & edit
+with no sign-up — you work as a guest. Sign in only when you want to save or
+share; signing in claims the plans you made as a guest into your account.
+
+Sharing and commenting require an account: public/shared plans are viewable by
+anyone with the link, but commenting on them needs an agent-native account.
+
+For fully offline, no-account use, run the Plans app locally and sync plans to
+your repo as MDX. This local mode is a separate advanced path, not the default
+hosted flow.
+
+If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
+do not keep retrying the tool. Authenticate the connector with
+\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
+instead re-run /mcp and choose Authenticate), then continue once the connector
+is available.
+
 Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
 not put shared secrets in skill files.
 `;
@@ -482,13 +721,15 @@ metadata:
 # UI Plan
 
 Use \`/ui-plan\` when the task is primarily about product UI, user flows,
-interaction states, component layout, or visual direction. The reviewable UI
+interaction details, component layout, or visual direction. The reviewable UI
 comes first; implementation detail comes after the user has something concrete to
 react to.
 
 \`/visual-plan\` remains the general command for architecture, backend, refactors,
-and mixed work. Use \`/visual-questions\` first when the user should answer intake
-questions, and \`/visualize-plan\` when a text plan already exists.
+and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
+prototype instead of static screens. Use \`/visual-questions\` only when the user
+explicitly wants visual intake before planning, and \`/visualize-plan\` when a text
+plan already exists.
 
 ## Plan Discipline
 
@@ -503,25 +744,35 @@ questions, and \`/visualize-plan\` when a text plan already exists.
   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; batch 2-4 before finalizing. Otherwise state
-  the assumption in the plan and proceed.
+  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. Call \`create-ui-plan\` with a UI-specific title, brief, source, repo path, and
+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.
-2. Compose the top canvas from the kit (see the cores below): the key artboards
+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.
-3. Continue below as a concise technical document — not a second copy of the
+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.
-4. Call \`get-plan-feedback\` before implementation, after review, after a long
-   pause, and before the final response. 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.
+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
 
@@ -531,87 +782,99 @@ code changes. Never claim feedback has been applied until \`get-plan-feedback\`
 the user has supplied it.
 
 <!-- SHARED-CORE:wireframe-canvas START -->
+
 ## Wireframe & Canvas Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
 \`/visualize-plan\`. It is the single source of truth for how wireframes and the
 canvas work. Do not paraphrase it per command.
 
-**The renderer owns all visual quality. You emit content, never styling.** Flex
-layout, fonts, density, spacing, theme, and the hand-drawn wobble all live in
-the app renderer. Never emit coordinates, CSS, pixel sizes, or raw HTML for a
-wireframe's internals. Your job is to pick a surface, compose real product
-content from the kit, and annotate — nothing else.
+**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 a declarative kit tree, not geometry:**
+**A wireframe block's data is an HTML screen plus a surface:**
 
 \`\`\`json
 {
-  "surface": "desktop",
-  "screen": [
-    { "el": "browserBar", "title": "tasklist" },
-    { "el": "row", "children": [
-      { "el": "sidebar", "children": [
-        { "el": "navItem", "label": "Inbox", "count": 12, "active": true },
-        { "el": "navItem", "label": "Today", "count": 4 },
-        { "el": "navItem", "label": "Done" }
-      ] },
-      { "el": "main", "children": [
-        { "el": "title", "text": "Today", "script": true },
-        { "el": "chips", "items": [
-          { "label": "All", "active": true }, { "label": "Active" }, { "label": "Done" }
-        ] },
-        { "el": "section", "label": "OVERDUE", "tone": "warn" },
-        { "el": "taskRow", "title": "Send invoice to Acme Co.", "due": "Yesterday", "dueTone": "warn", "prio": 1 },
-        { "el": "taskRow", "title": "Reply to design feedback", "due": "Today", "prio": 2 }
-      ] }
-    ] }
-  ]
+  "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>"
 }
 \`\`\`
 
-The renderer maps each node to a flex kit component and applies one whole-frame
-wobble. Layout is always flex: \`row\`, \`col\`, \`sidebar\`, and \`main\` set the flex
-direction; everything aligns by construction, so you never get overlap or drift.
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
+- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
+  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
+- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
+- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
+  primary button.
+
+**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
+\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
+(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
+\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
+and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
+renderer owns the sketch/clean font.
+
+**Lay out with inline \`style\` flex/grid.** You write the real layout —
+\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
 
 **Surface presets — match the real footprint, never default to desktop+mobile.**
 Pick the \`surface\` that matches what the user will actually see:
 
-- \`desktop\`: a full page or app shell.
+- \`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.
-- \`browser\`: a page that needs a browser chrome frame around it.
 
+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.
 
-**Node vocabulary (\`el\` values).** Every node is \`{ el, ...props, children? }\`:
-
-- Layout: \`screen\`, \`row\`, \`col\`, \`sidebar\`, \`main\`, \`card{children}\`,
-  \`column{title,count?,children}\`, \`box{children,dashed?}\`, \`divider\`.
-- Chrome: \`browserBar{title}\`, \`statusBar\`, \`searchBar\`, \`toolbar\`.
-- Navigation: \`navItem{label,count?,active?,dot?}\`, \`tabs\`/\`chips{items:[{label,active?}]}\`,
-  \`chip{label,active?}\`, \`pill{label,tone?}\`.
-- Content: \`title{text,script?}\`, \`text{value,color?,weight?}\`,
-  \`lines{n?,widths?}\`, \`section{label,tone?}\`,
-  \`taskRow{title,note?,due?,dueTone?,prio?,done?}\`, \`kv{rows:[{k,v}]}\`,
-  \`avatar\`, \`iconSquare{active?}\`.
-- Inputs: \`field{label?,value?,placeholder?,area?}\`, \`check{done?,shape?}\`,
-  \`btn{label,solid?,full?}\`, \`fab{icon?}\`.
-
-Put **real product content** in props: real labels, real dates, real counts,
-real button text grounded in the actual screen or component you read. Use
-\`lines\`/\`text\` (with no \`value\`) only for genuine placeholder body copy — never
-fill a screen with gray placeholder bars. Buttons (\`btn\`, \`fab\`) must read as
-actionable controls.
-
-**Default crisp.** Sketchiness is a low default (a subtle single wobble over the
-whole frame), not a heavy scribble. Do not ask for or assume a heavy sketch
-look.
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
+fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
+built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a \`custom-html\` document block
+to fake a loader, and never move a mockup out of the canvas — mockups always
+live in canvas artboards.
+
+**Editing an existing mockup.** To change one element, text, or color in an
+existing html mockup, do NOT regenerate the frame — call \`update-visual-plan\`
+with \`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
+first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
+occurrence. The result is re-sanitized.
 
 **Canvas annotations are designer notes on the artboard.** When a top canvas is
 present, sprinkle Figma-style notes near the frames they explain: a short
@@ -622,8 +885,16 @@ 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.
 
-**Patching.** Edit one wireframe node, canvas annotation, or block with targeted \`contentPatches\`
-(for example \`update-wireframe-node\`, \`update-block\`, \`replace-blocks\`) rather
+**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
@@ -632,14 +903,71 @@ frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
 \`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
 patch action normalizes the MDX back into the same JSON runtime model. JSON is
 the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit \`rich-text\` prose inline; agents should still use
+\`update-rich-text\` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Good example — a contacts list, surface \`browser\`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+\`\`\`html
+<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+\`\`\`
+
+**Mockups belong in the top visual review area.** Static visuals live on the
+canvas; multi-step flows get both canvas wireframes and a prototype. When the
+user asks for a mockup, UI state, loading state, layout, screen, or visual
+comparison, make the canvas the primary home for that static visual. When the
+user asks for a prototype or the plan contains a sequence the reviewer must
+feel, keep the canvas artboards and add \`content.prototype\` so the top surface
+shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
+implementation, but they should not host the primary mockup or prototype just
+because \`custom-html\`, screenshots, or prose are easier to produce. If the
+canvas/prototype surface cannot represent the requested fidelity, still keep the
+closest top-surface representation and call out or extend the needed renderer
+capability.
+
+**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
+nodes instead of \`html\`; the renderer still accepts and displays it, but new
+plans emit \`html\`. Do not author fresh kit-tree screens — write the HTML mockup
+instead. Likewise, old or imported plans may carry coordinate-based regions or
+free-float x/y on notes or artboards; those are legacy escape hatches the
+renderer still shows but you must never produce. The \`surface\` drives the aspect
+and footprint, the canvas auto-places artboards, and the gutter parks notes by
+\`targetId\` + \`placement\`; never supply width, height, or coordinates for a new
+plan.
 
-**Legacy imports only.** Old or imported plans may carry coordinate-based
-regions or a full standalone HTML document; the renderer still displays them.
-Never emit geometry, regions, or a standalone HTML document for a new plan —
-compose the kit tree instead.
 <!-- SHARED-CORE:wireframe-canvas END -->
 
 <!-- SHARED-CORE:document-quality START -->
+
 ## Document Quality Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
@@ -656,14 +984,19 @@ 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.
 
-**Canvas and document never duplicate each other.** The UI story lives on the
-canvas with on-canvas annotations; the document carries the technical depth the
-canvas cannot show — concrete file/symbol maps, API and data contracts, code
-snippets, migration or implementation phases, risks, and validation. Repeat a
-wireframe in the document only for a genuinely new detail view or comparison.
-Skip the canvas entirely for non-visual work and write a clean rich document.
+**Top visuals and document never duplicate each other.** The UI story lives in
+the top visual surface: canvas artboards for static inspection, plus prototype
+tabs when the flow should be functional. The document carries the technical depth
+the visuals cannot show — concrete file/symbol maps, API and data contracts,
+code snippets, migration or implementation phases, risks, and validation. Repeat
+a wireframe in the document only for a genuinely new detail view or comparison.
+Skip the visual surface entirely for non-visual work and write a clean rich
+document.
 
-**Use the right block, and make it carry substance:**
+**Use the right block, and make it carry substance.** For the authoritative,
+machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
+— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
+so you never emit a block the editor cannot render or round-trip:
 
 - \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
 - \`implementation-map\` / \`code-tabs\` for the file map: file path, the
@@ -681,45 +1014,70 @@ Skip the canvas entirely for non-visual work and write a clean rich document.
   visual unless the tab is intentionally document-only.
 - \`table\`, \`checklist\`, \`callout\` for scannable structure.
 
-**Open questions are callouts, not buried prose.** Surface anything unresolved in
-a dedicated open-questions / needs-clarification block. Never put a
-questions/decisions wall inside the plan narrative.
+**Open questions live at the bottom as a form when answers would change the
+plan.** Surface answerable unresolved decisions in a final \`question-form\`
+block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
+\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
+and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
+Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
+relevant section. Never bury a questions/decisions wall inside the plan
+narrative.
 
 **\`custom-html\` is a bounded escape hatch only** — a single complete fragment
-inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a placeholder,
-density demo, or proof that custom HTML works. Prefer the native blocks; they
-cover real plans.
+inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
+placeholder, density demo, or proof that custom HTML works. Prefer the native
+blocks for normal plans. It may support supplemental demos or references, but it
+is never the primary home for a requested mockup, UI state, or visual
+comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
+product fix is canvas support for that artifact type, not moving the mockup into
+the document.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
 unreadable diagrams before asking for approval.
+
 <!-- SHARED-CORE:document-quality END -->
 
 <!-- SHARED-CORE:exemplar START -->
+
 ## Good vs. Bad Exemplar
 
-**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard
-composed from the kit — a sidebar of real \`navItem\`s (\`Inbox 12\`, \`Today 4\`,
-\`Done\`), a \`main\` with a scripted \`title\`, real \`chips\`, a \`section\` labeled
-\`OVERDUE\`, and \`taskRow\`s carrying real titles, due dates, and priorities — one
-subtle whole-frame wobble, correct desktop footprint, and plain-text designer
-notes spaced off the frames 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. This is the bar.
-
-**BAD.** Empty coordinate boxes placed by \`x/y/width/height\`, gray placeholder
-bars "insinuating" text, crisp double-bordered rectangles or a heavy scribble, a
-forced desktop + mobile pair for a popover, floating bordered annotation cards
-hugging the frames, and a marketing-style document with a hero heading and value
-props that just restates what the canvas already shows. Never produce this.
+**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard whose
+\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
+\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
+filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
+titles, due dates, and a primary \`button.primary\` — styled only through bare
+elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, an \`implementation-map\` naming the real components and actions
+with short highlighted snippets, a \`decision\` card weighing two real approaches,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+\`data-goto\` controls for the sequence. This is the bar.
+
+**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
+instead of \`html\`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Never produce this.
+
 <!-- SHARED-CORE:exemplar END -->
 
 ## Tool Guidance
 
 - \`create-ui-plan\`: create the UI-first structured visual plan.
-- \`create-visual-questions\`: run a visual intake form before the UI plan.
+- \`create-prototype-plan\`: create a prototype-first plan when UI review needs a
+  functional live prototype.
+- \`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 \`/ui-plan\` preflight.
 - \`update-visual-plan\`: revise content, mockups, comments, or handoff notes;
   prefer targeted \`contentPatches\`.
 - \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
@@ -729,20 +1087,218 @@ props that just restates what the canvas already shows. Never produce this.
 - \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
 - \`get-visual-plan\`: inspect the current structured plan, exported HTML, and
   annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed reviewer comments before coding.
+- \`get-plan-feedback\`: read unconsumed reviewer comments before coding; it
+  returns grouped threads, exact anchor details, expected resolver, and recent
+  review-event payloads so agents can act only on the comments meant for them.
 - \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
   files for repo check-in.
 
 When the user critiques a plan's look or structure, fix the renderer or this
 skill — never hand-edit one stored plan. Turn feedback into better guidance.
 
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`.
+## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and
+authenticates it in the same step (a one-time browser sign-in at setup — this is
+intended), so the first tool call does not hit an OAuth wall:
+
+\`\`\`bash
+agent-native skills add visual-plan
+\`\`\`
+
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
+\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+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 PROTOTYPE_PLAN_SKILL_MD = `---
+name: prototype-plan
+description: >-
+  Use Agent-Native Plans for /prototype-plan when work needs a functional
+  prototype-first plan, static mocks, comments, review toggles, or conversion
+  from a visual plan.
+metadata:
+  visibility: exported
+---
+
+# Prototype Plan
+
+\`/prototype-plan\` creates a plan whose primary review surface is a live,
+functional prototype above the document. Use it when the user needs to feel a
+flow, operate basic UI state, or comment on interaction before implementation
+hardens the decision.
+
+## Rule
+
+Make the prototype answer a concrete question. The plan should say what is being
+tested, show the functional prototype first, then keep static mocks and implementation
+notes in the document below.
+
+## When To Use
+
+Use \`/prototype-plan\` when the user asks for a prototype, wants to click through
+and operate UI states, needs design review before code, wants comments pinned to
+live screens, or asks to move a visual plan into a prototype.
+
+Prefer \`/visual-plan\` for architecture, data flow, or non-interactive planning.
+Prefer \`/ui-plan\` when static screen review is enough. Use \`/visualize-plan\`
+first only when the user hands you an existing Markdown/Codex/Claude plan that
+needs a visual companion before becoming interactive.
+
+## Core Workflow
+
+1. Inspect the real codebase and decide the question the prototype should
+   answer. Good examples: "Does this onboarding flow feel short enough?" or
+   "Which dashboard density should we implement?"
+2. Call \`create-prototype-plan\` with a title, brief, and screen HTML. Default to
+   one functional prototype screen when local UI behavior is enough; use 2-4
+   screens only for true routes, steps, or materially different contexts. The
+   returned plan opens with the prototype viewer on top and static mocks, flow
+   diagram, implementation map, and verification below.
+3. Make controls actually work. Use the renderer's safe Alpine-like directives:
+   \`x-data\`, \`x-model\`, \`x-for\`, \`x-text\`, \`x-show\`, \`:class\`, \`@click\`, and
+   \`@keydown.enter\`. Use safe helper verbs such as \`remove(list, item)\`,
+   \`setAll(list, 'done', true)\`, \`removeWhere(list, 'done', true)\`, and counters
+   such as \`count(list)\`, \`countWhere(list, 'done', true)\`, and
+   \`remaining(list, 'done')\` when they help. Use \`data-goto="screen-id"\` only
+   for true screen/route changes, not for every button press.
+4. Show important app feedback inside the prototype itself: selected filters,
+   checked rows, typed drafts, validation messages, permissions, progress, or
+   empty states.
+5. Surface the returned Plans link and ask the user to click through, comment on
+   the prototype or static mocks, and approve the direction before code changes.
+6. Before implementing or revising, call \`get-plan-feedback\`. Treat prototype
+   anchors, screenshots, and resolver intent as the source of truth.
+7. Update with \`update-visual-plan\` content patches. Use
+   \`patch-prototype-html\`, \`update-prototype-screen\`, or \`set-prototype\` for
+   targeted prototype edits instead of regenerating the whole plan.
+
+## Converting A Visual Plan
+
+When a visual plan already has HTML canvas wireframes, call
+\`convert-visual-plan-to-prototype\` with the plan id. This derives prototype
+screens from the canvas frames, preserves the canvas/static mocks by default,
+and changes the top review surface to the prototype viewer.
+
+Use \`removeCanvas: true\` only when the user explicitly wants the old canvas
+gone. Otherwise keep static mocks available for source export and detailed
+review.
+
+## Prototype Screen HTML
+
+Write bounded semantic HTML fragments only:
+
+\`\`\`html
+<div style="display:flex;flex-direction:column;gap:14px;padding:18px;height:100%">
+  <header style="display:flex;justify-content:space-between;gap:12px">
+    <div>
+      <h1>Launch checklist</h1>
+      <p class="wf-muted">Reviewer can add, complete, filter, and remove tasks.</p>
+    </div>
+    <span class="wf-pill accent">Live prototype</span>
+  </header>
+  <section
+    class="wf-card"
+    x-data="{ draft: '', filter: 'all', todos: [{ text: 'Check copy', done: false }, { text: 'Confirm owner', done: true }] }"
+    style="display:flex;flex-direction:column;gap:10px"
+  >
+    <div style="display:flex;gap:8px">
+      <input x-model="draft" @keydown.enter="draft && todos.push({ text: draft, done: false }); draft = ''" placeholder="Add task" />
+      <button class="primary" @click="draft && todos.push({ text: draft, done: false }); draft = ''">Add</button>
+    </div>
+    <div style="display:flex;gap:8px">
+      <button @click="filter = 'all'" :class="{ primary: filter === 'all' }">All</button>
+      <button @click="filter = 'done'" :class="{ primary: filter === 'done' }">Done</button>
+      <button @click="setAll(todos, 'done', true)">Mark all done</button>
+    </div>
+    <p class="wf-muted"><span x-text="remaining(todos, 'done')"></span> open / <span x-text="count(todos)"></span> total</p>
+    <div
+      class="wf-box"
+      x-for="todo in todos"
+      x-show="filter === 'all' || (filter === 'done' && todo.done)"
+      :class="{ 'is-done': todo.done }"
+      style="display:flex;justify-content:space-between;gap:10px"
+    >
+      <label style="display:flex;gap:8px"><input type="checkbox" x-model="todo.done" /><span x-text="todo.text"></span></label>
+      <button @click="remove(todos, todo)">Remove</button>
+    </div>
+    <button @click="removeWhere(todos, 'done', true)">Clear completed</button>
+  </section>
+</div>
+\`\`\`
+
+Use real labels, counts, dates, and controls grounded in the target app. Keep
+surfaces honest: \`browser\` for web pages, \`desktop\` for app shells, \`mobile\`
+only for real mobile work, \`panel\` for side panels, and \`popover\` for menus.
+
+Do not include \`<html>\`, \`<body>\`, \`<script>\`, \`<style>\`, browser \`on*\`
+handler attributes such as \`onclick\`, fake APIs, raw secrets, or customer data.
+The renderer owns sketchy/clean mode, theme, surface sizing, rough outlines, and
+comment overlays.
+
+## Review Surface
+
+Prototype plans support:
+
+- real local controls through safe prototype directives
+- optional screen/route transitions from \`data-goto\`
+- rough vs clean mode through the shared wireframe toggle
+- dark vs light mode through the shared theme toggle
+- comment visibility from the prototype toolbar
+- Figma-style comments pinned directly on live prototype screens
+- a popout URL with \`?prototype=1\` for focused browser review
+- static wireframe mocks in the document body where they help implementation
+
+## Source Files
+
+Runtime JSON is canonical. Source export uses:
+
+- \`plan.mdx\` for document blocks
+- \`prototype.mdx\` for \`<Prototype>\`, \`<PrototypeScreen>\`, and
+  \`<PrototypeTransition>\`
+- \`canvas.mdx\` for static mocks when a canvas is present
+- \`.plan-state.json\` for persisted viewport state
+
+Patch source with \`patch-visual-plan-source\` only when the user wants
+source-control friendly edits. Patch runtime content when the user is simply
+reviewing and iterating.
+
+## Related Skills
+
+- \`visual-plan\`
+- \`ui-plan\`
+- \`visualize-plan\`
+- \`visual-questions\`
 `;
 export const VISUAL_QUESTIONS_SKILL_MD = `---
 name: visual-questions
 description: >-
-  Use Agent-Native Plans to ask rich visual intake questions before creating a
-  UI plan or visual plan.
+  Use Agent-Native Plans to ask rich visual intake questions when
+  /visual-questions is explicitly requested before creating a UI plan or visual
+  plan.
 metadata:
   visibility: both
 ---
@@ -752,8 +1308,8 @@ metadata:
 Use \`/visual-questions\` when the next best step is not a plan yet, but a
 reviewable visual intake: single-choice chips, multi-select chips, freeform
 notes, mockup choices, sketch diagrams, and a generated answer summary that feeds
-the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`, and
-\`/visualize-plan\`.
+the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`,
+\`/prototype-plan\`, and \`/visualize-plan\`.
 
 ## When To Use
 
@@ -764,9 +1320,12 @@ the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`, and
   than answering text-only prompts.
 
 Gate hard: skip this for tiny, unambiguous changes. If the agent can reasonably
-infer the answer, prefer \`/ui-plan\` or \`/visual-plan\` directly and put
+infer the answer, prefer \`/ui-plan\`, \`/prototype-plan\`, or \`/visual-plan\` directly and put
 assumptions in the plan.
 
+Visual questions are an explicit intake command, not an automatic preflight for
+\`/visual-plan\`, \`/ui-plan\`, or \`/prototype-plan\`.
+
 ## Workflow
 
 1. Call \`create-visual-questions\` with a clear title, brief, source, and repo
@@ -774,10 +1333,11 @@ assumptions in the plan.
 2. Omit \`questions\` for the default UI intake. Provide a custom \`questions\` array
    only when the task has domain-specific choices.
 3. Surface the returned Plans link and ask the user to answer visually.
-4. The generated summary drives the next step: \`create-ui-plan\` for UI flows,
+4. The generated summary drives the next step: \`create-ui-plan\` for static UI
+   review, \`create-prototype-plan\` for click-through UI flows,
    \`create-visual-plan\` for general plans, \`visualize-plan\` when a text plan
-   already exists, or \`update-visual-plan\` with targeted \`contentPatches\` to fold
-   answers into an active plan.
+   already exists, or \`update-visual-plan\` with targeted \`contentPatches\` to
+   fold answers into an active plan.
 5. If the user leaves comments, call \`get-plan-feedback\` before using the answers.
 
 ## Question Types
@@ -812,6 +1372,8 @@ desktop/mobile pair for a popover, panel, or component.
 - \`get-visual-plan\`: inspect the current visual question plan.
 - \`get-plan-feedback\`: read comments before creating or updating the next plan.
 - \`create-ui-plan\`: create a UI-first plan from the answers.
+- \`create-prototype-plan\`: create a prototype-first plan from the answers when
+  interaction feel matters.
 - \`create-visual-plan\`: create a general visual plan from the answers.
 - \`visualize-plan\`: enrich an existing text plan after answers are gathered.
 - \`export-visual-plan\`: export answer plans as HTML, Markdown fallback,
@@ -819,14 +1381,50 @@ desktop/mobile pair for a popover, panel, or component.
 - \`read-visual-plan-source\` / \`patch-visual-plan-source\`: inspect or patch the
   MDX source if another agent is operating from checked-in plan files.
 
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`.
+## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and
+authenticates it in the same step (a one-time browser sign-in at setup — this is
+intended), so the first tool call does not hit an OAuth wall:
+
+\`\`\`bash
+agent-native skills add visual-plan
+\`\`\`
+
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
+\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+register the connector without authenticating, then run
+\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
+
+**Browser (people you share with).** Open the Plans editor and create & edit
+with no sign-up — you work as a guest. Sign in only when you want to save or
+share; signing in claims the plans you made as a guest into your account.
+
+Sharing and commenting require an account: public/shared plans are viewable by
+anyone with the link, but commenting on them needs an agent-native account.
+
+For fully offline, no-account use, run the Plans app locally and sync plans to
+your repo as MDX. This local mode is a separate advanced path, not the default
+hosted flow.
+
+If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
+do not keep retrying the tool. Authenticate the connector with
+\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
+instead re-run /mcp and choose Authenticate), then continue once the connector
+is available.
+
+Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
+not put shared secrets in skill files.
 `;
 export const VISUALIZE_PLAN_SKILL_MD = `---
 name: visualize-plan
 description: >-
   Convert an existing Codex, Claude Code, Markdown, or pasted plan into an
-  Agent-Native Plans visual companion with diagrams, wireframes, annotations, and
-  feedback.
+  Agent-Native Plans visual companion with diagrams, wireframes, prototypes,
+  annotations, and feedback.
 metadata:
   visibility: exported
 ---
@@ -836,8 +1434,14 @@ metadata:
 Use \`/visualize-plan\` when a plan already exists and the user wants it easier to
 review. The native Codex or Claude Code plan can stay where it is; Agent-Native
 Plans creates a structured visual companion beside it — diagrams, wireframes,
-state sketches, option cards, and comment prompts instead of a wall of text. It
-still reads like a plan, not a marketing page.
+state sketches, functional prototypes, option cards, and comment prompts instead
+of a wall of text. It still reads like a plan, not a marketing page.
+
+Use \`/prototype-plan\` instead when the user wants a functional prototype as the first
+artifact and there is no text plan to preserve. When a text plan already exists,
+\`/visualize-plan\` should decide whether it needs no visual surface, canvas only,
+or canvas + prototype; call \`convert-visual-plan-to-prototype\` after
+visualization when its HTML wireframes should drive a prototype review.
 
 ## Plan Discipline
 
@@ -849,112 +1453,160 @@ still reads like a plan, not a marketing page.
   edits while building or reviewing the companion.
 - **The companion is the approval gate.** Ask the user to review and approve the
   direction before you write code, and name which files/areas the work touches.
-  Carry unresolved assumptions and open questions into a clear block instead of
-  guessing silently.
+  Carry answerable unresolved assumptions and open questions into a bottom
+  \`question-form\` block instead of guessing silently.
 
 ## Workflow
 
 1. Gather the existing plan text from the user's paste, a referenced file, or
    recent visible agent context. Do not invent the source plan. If no plan text
-   exists and the work is UI-heavy, use \`/ui-plan\` instead.
+   exists and the work is UI-heavy, use \`/ui-plan\` or \`/prototype-plan\` instead.
 2. Call \`visualize-plan\` with \`planText\`, \`title\`, \`brief\`, \`source\`, and
    \`repoPath\` when available.
 3. Surface the returned Plans link or inline MCP App.
-4. Enrich the import with \`update-visual-plan\` (prefer targeted \`contentPatches\`):
-   add a canvas with wireframes for user-visible UI, diagrams for architecture or
-   data flow, option cards for real tradeoffs, and explicit open questions. Apply
-   the two cores below — the companion must meet the same quality bar as a fresh
-   plan, not be a thinner ruleset. Label inferred visuals as inferred. When the
-   user wants source-control friendly edits, use \`patch-visual-plan-source\`
-   against the MDX files instead of regenerating the plan.
+4. Decide the top visual surface with the rules below, then enrich the import
+   with \`update-visual-plan\` (prefer targeted \`contentPatches\`): add canvas
+   wireframes for user-visible UI, add \`content.prototype\` for multi-step flows,
+   add diagrams for architecture or data flow, add option cards for real
+   tradeoffs, and add explicit open questions. Apply the two cores below — the
+   companion must meet the same quality bar as a fresh plan, not be a thinner
+   ruleset. Label inferred visuals as inferred. When the user wants
+   source-control friendly edits, use \`patch-visual-plan-source\` against the MDX
+   files instead of regenerating the plan. If the user asks to make the visual
+   companion functional and the canvas contains HTML wireframes, call
+   \`convert-visual-plan-to-prototype\`.
 5. Ask the user to react, then call \`get-plan-feedback\` before implementing,
    after review, and before the final response.
 6. Treat imported text as source material. The structured visual plan and
    comments are the review surface; HTML is the export receipt. Do not replace a
    native plan unless the user asks.
 
+## Visual Surface Choice
+
+Choose the surface after reading the source plan and before enriching it. Do not
+add visual chrome by default:
+
+- **No visual surface** when the imported plan is architecture-only,
+  backend-only, data migration, copy-only, or otherwise non-visual. Keep the
+  companion as a strong document and add diagrams only when relationships need a
+  visual explanation.
+- **Canvas only** when the source plan includes one static screen, a before/after
+  comparison, a component state, a small popover, or a visual direction that does
+  not require clicking. Put those wireframes in \`content.canvas\` and omit
+  \`content.prototype\`.
+- **Canvas + prototype** when the source plan describes a multi-step UI flow,
+  meaningful interactive app behavior, onboarding, wizard, review/approval flow,
+  navigation change, or any sequence the reviewer needs to operate. Keep the
+  static wireframes in
+  \`content.canvas\`, add the aligned functional prototype in
+  \`content.prototype\`, and rely on the top visual tabs to switch between them.
+- **Prototype-first conversion** when an already-visualized plan's HTML
+  wireframes should become functional. Use \`convert-visual-plan-to-prototype\` for
+  an existing canvas, or \`update-visual-plan\` with \`set-prototype\` when the
+  imported plan needs a hand-authored prototype that does not map cleanly from
+  the canvas. Keep static mocks unless the user explicitly asks to remove them.
+
+For mixed canvas + prototype companions, reuse the same real labels, states, and
+screen ids across both surfaces. The canvas is the inspectable static reference;
+the prototype is the interactive version of that same flow, not a separate
+design direction. If the imported plan only has text, add HTML wireframes before
+calling \`convert-visual-plan-to-prototype\`; never convert a diagram-only or
+empty canvas into a fake prototype.
+
 <!-- SHARED-CORE:wireframe-canvas START -->
+
 ## Wireframe & Canvas Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
 \`/visualize-plan\`. It is the single source of truth for how wireframes and the
 canvas work. Do not paraphrase it per command.
 
-**The renderer owns all visual quality. You emit content, never styling.** Flex
-layout, fonts, density, spacing, theme, and the hand-drawn wobble all live in
-the app renderer. Never emit coordinates, CSS, pixel sizes, or raw HTML for a
-wireframe's internals. Your job is to pick a surface, compose real product
-content from the kit, and annotate — nothing else.
+**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 a declarative kit tree, not geometry:**
+**A wireframe block's data is an HTML screen plus a surface:**
 
 \`\`\`json
 {
-  "surface": "desktop",
-  "screen": [
-    { "el": "browserBar", "title": "tasklist" },
-    { "el": "row", "children": [
-      { "el": "sidebar", "children": [
-        { "el": "navItem", "label": "Inbox", "count": 12, "active": true },
-        { "el": "navItem", "label": "Today", "count": 4 },
-        { "el": "navItem", "label": "Done" }
-      ] },
-      { "el": "main", "children": [
-        { "el": "title", "text": "Today", "script": true },
-        { "el": "chips", "items": [
-          { "label": "All", "active": true }, { "label": "Active" }, { "label": "Done" }
-        ] },
-        { "el": "section", "label": "OVERDUE", "tone": "warn" },
-        { "el": "taskRow", "title": "Send invoice to Acme Co.", "due": "Yesterday", "dueTone": "warn", "prio": 1 },
-        { "el": "taskRow", "title": "Reply to design feedback", "due": "Today", "prio": 2 }
-      ] }
-    ] }
-  ]
+  "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>"
 }
 \`\`\`
 
-The renderer maps each node to a flex kit component and applies one whole-frame
-wobble. Layout is always flex: \`row\`, \`col\`, \`sidebar\`, and \`main\` set the flex
-direction; everything aligns by construction, so you never get overlap or drift.
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
+- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
+  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
+- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
+- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
+  primary button.
+
+**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
+\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
+(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
+\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
+and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
+renderer owns the sketch/clean font.
+
+**Lay out with inline \`style\` flex/grid.** You write the real layout —
+\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
 
 **Surface presets — match the real footprint, never default to desktop+mobile.**
 Pick the \`surface\` that matches what the user will actually see:
 
-- \`desktop\`: a full page or app shell.
+- \`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.
-- \`browser\`: a page that needs a browser chrome frame around it.
 
+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.
 
-**Node vocabulary (\`el\` values).** Every node is \`{ el, ...props, children? }\`:
-
-- Layout: \`screen\`, \`row\`, \`col\`, \`sidebar\`, \`main\`, \`card{children}\`,
-  \`column{title,count?,children}\`, \`box{children,dashed?}\`, \`divider\`.
-- Chrome: \`browserBar{title}\`, \`statusBar\`, \`searchBar\`, \`toolbar\`.
-- Navigation: \`navItem{label,count?,active?,dot?}\`, \`tabs\`/\`chips{items:[{label,active?}]}\`,
-  \`chip{label,active?}\`, \`pill{label,tone?}\`.
-- Content: \`title{text,script?}\`, \`text{value,color?,weight?}\`,
-  \`lines{n?,widths?}\`, \`section{label,tone?}\`,
-  \`taskRow{title,note?,due?,dueTone?,prio?,done?}\`, \`kv{rows:[{k,v}]}\`,
-  \`avatar\`, \`iconSquare{active?}\`.
-- Inputs: \`field{label?,value?,placeholder?,area?}\`, \`check{done?,shape?}\`,
-  \`btn{label,solid?,full?}\`, \`fab{icon?}\`.
-
-Put **real product content** in props: real labels, real dates, real counts,
-real button text grounded in the actual screen or component you read. Use
-\`lines\`/\`text\` (with no \`value\`) only for genuine placeholder body copy — never
-fill a screen with gray placeholder bars. Buttons (\`btn\`, \`fab\`) must read as
-actionable controls.
-
-**Default crisp.** Sketchiness is a low default (a subtle single wobble over the
-whole frame), not a heavy scribble. Do not ask for or assume a heavy sketch
-look.
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
+fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
+built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a \`custom-html\` document block
+to fake a loader, and never move a mockup out of the canvas — mockups always
+live in canvas artboards.
+
+**Editing an existing mockup.** To change one element, text, or color in an
+existing html mockup, do NOT regenerate the frame — call \`update-visual-plan\`
+with \`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
+first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
+occurrence. The result is re-sanitized.
 
 **Canvas annotations are designer notes on the artboard.** When a top canvas is
 present, sprinkle Figma-style notes near the frames they explain: a short
@@ -965,8 +1617,16 @@ 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.
 
-**Patching.** Edit one wireframe node, canvas annotation, or block with targeted \`contentPatches\`
-(for example \`update-wireframe-node\`, \`update-block\`, \`replace-blocks\`) rather
+**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
@@ -975,14 +1635,71 @@ frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
 \`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
 patch action normalizes the MDX back into the same JSON runtime model. JSON is
 the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit \`rich-text\` prose inline; agents should still use
+\`update-rich-text\` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard you place on the canvas must carry an \`html\` wireframe (or reference a wireframe block via \`blockId\`) — a label-only frame renders as an empty dashed box and is rejected at parse time. If you only have a title, write it as a section header or annotation, not an empty artboard.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Good example — a contacts list, surface \`browser\`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+\`\`\`html
+<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%">
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div class="wf-card" style="display:flex;flex-direction:column;gap:0;padding:0">
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Jane Cooper</strong><br /><small>jane@acme.co</small></div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"></div>
+      <div style="flex:1"><strong>Marcus Lee</strong><br /><small>marcus@globex.io</small></div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+\`\`\`
+
+**Mockups belong in the top visual review area.** Static visuals live on the
+canvas; multi-step flows get both canvas wireframes and a prototype. When the
+user asks for a mockup, UI state, loading state, layout, screen, or visual
+comparison, make the canvas the primary home for that static visual. When the
+user asks for a prototype or the plan contains a sequence the reviewer must
+feel, keep the canvas artboards and add \`content.prototype\` so the top surface
+shows Wireframes / Prototype tabs. Document blocks can explain, compare, or map
+implementation, but they should not host the primary mockup or prototype just
+because \`custom-html\`, screenshots, or prose are easier to produce. If the
+canvas/prototype surface cannot represent the requested fidelity, still keep the
+closest top-surface representation and call out or extend the needed renderer
+capability.
+
+**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
+nodes instead of \`html\`; the renderer still accepts and displays it, but new
+plans emit \`html\`. Do not author fresh kit-tree screens — write the HTML mockup
+instead. Likewise, old or imported plans may carry coordinate-based regions or
+free-float x/y on notes or artboards; those are legacy escape hatches the
+renderer still shows but you must never produce. The \`surface\` drives the aspect
+and footprint, the canvas auto-places artboards, and the gutter parks notes by
+\`targetId\` + \`placement\`; never supply width, height, or coordinates for a new
+plan.
 
-**Legacy imports only.** Old or imported plans may carry coordinate-based
-regions or a full standalone HTML document; the renderer still displays them.
-Never emit geometry, regions, or a standalone HTML document for a new plan —
-compose the kit tree instead.
 <!-- SHARED-CORE:wireframe-canvas END -->
 
 <!-- SHARED-CORE:document-quality START -->
+
 ## Document Quality Core
 
 This section is shared, word for word, by \`/visual-plan\`, \`/ui-plan\`, and
@@ -999,14 +1716,19 @@ 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.
 
-**Canvas and document never duplicate each other.** The UI story lives on the
-canvas with on-canvas annotations; the document carries the technical depth the
-canvas cannot show — concrete file/symbol maps, API and data contracts, code
-snippets, migration or implementation phases, risks, and validation. Repeat a
-wireframe in the document only for a genuinely new detail view or comparison.
-Skip the canvas entirely for non-visual work and write a clean rich document.
+**Top visuals and document never duplicate each other.** The UI story lives in
+the top visual surface: canvas artboards for static inspection, plus prototype
+tabs when the flow should be functional. The document carries the technical depth
+the visuals cannot show — concrete file/symbol maps, API and data contracts,
+code snippets, migration or implementation phases, risks, and validation. Repeat
+a wireframe in the document only for a genuinely new detail view or comparison.
+Skip the visual surface entirely for non-visual work and write a clean rich
+document.
 
-**Use the right block, and make it carry substance:**
+**Use the right block, and make it carry substance.** For the authoritative,
+machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
+— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
+so you never emit a block the editor cannot render or round-trip:
 
 - \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
 - \`implementation-map\` / \`code-tabs\` for the file map: file path, the
@@ -1024,61 +1746,126 @@ Skip the canvas entirely for non-visual work and write a clean rich document.
   visual unless the tab is intentionally document-only.
 - \`table\`, \`checklist\`, \`callout\` for scannable structure.
 
-**Open questions are callouts, not buried prose.** Surface anything unresolved in
-a dedicated open-questions / needs-clarification block. Never put a
-questions/decisions wall inside the plan narrative.
+**Open questions live at the bottom as a form when answers would change the
+plan.** Surface answerable unresolved decisions in a final \`question-form\`
+block titled "Open Questions". Use \`single\` or \`multi\` for clear choices,
+\`freeform\` for constraints, \`recommended: true\` for the default you would pick,
+and option \`wireframe\` / \`diagram\` previews for visual directions when useful.
+Keep non-answerable assumptions or risks as concise \`callout\` blocks in the
+relevant section. Never bury a questions/decisions wall inside the plan
+narrative.
 
 **\`custom-html\` is a bounded escape hatch only** — a single complete fragment
-inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a placeholder,
-density demo, or proof that custom HTML works. Prefer the native blocks; they
-cover real plans.
+inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
+placeholder, density demo, or proof that custom HTML works. Prefer the native
+blocks for normal plans. It may support supplemental demos or references, but it
+is never the primary home for a requested mockup, UI state, or visual
+comparison. If fidelity requires HTML/CSS, image capture, or real React/CSS, the
+product fix is canvas support for that artifact type, not moving the mockup into
+the document.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
 unreadable diagrams before asking for approval.
+
 <!-- SHARED-CORE:document-quality END -->
 
 <!-- SHARED-CORE:exemplar START -->
+
 ## Good vs. Bad Exemplar
 
-**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard
-composed from the kit — a sidebar of real \`navItem\`s (\`Inbox 12\`, \`Today 4\`,
-\`Done\`), a \`main\` with a scripted \`title\`, real \`chips\`, a \`section\` labeled
-\`OVERDUE\`, and \`taskRow\`s carrying real titles, due dates, and priorities — one
-subtle whole-frame wobble, correct desktop footprint, and plain-text designer
-notes spaced off the frames 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. This is the bar.
-
-**BAD.** Empty coordinate boxes placed by \`x/y/width/height\`, gray placeholder
-bars "insinuating" text, crisp double-bordered rectangles or a heavy scribble, a
-forced desktop + mobile pair for a popover, floating bordered annotation cards
-hugging the frames, and a marketing-style document with a hero heading and value
-props that just restates what the canvas already shows. Never produce this.
+**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard whose
+\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
+\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
+filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
+titles, due dates, and a primary \`button.primary\` — styled only through bare
+elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, an \`implementation-map\` naming the real components and actions
+with short highlighted snippets, a \`decision\` card weighing two real approaches,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+\`data-goto\` controls for the sequence. This is the bar.
+
+**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
+instead of \`html\`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Never produce this.
+
 <!-- SHARED-CORE:exemplar END -->
 
 ## Tool Guidance
 
 - \`visualize-plan\`: create the visual companion from the existing text plan.
 - \`update-visual-plan\`: enrich the import; prefer targeted \`contentPatches\` over
-  replacing the whole content.
+  replacing the whole content. Use \`set-prototype\`, \`patch-prototype-html\`,
+  \`update-prototype-screen\`, and \`patch-wireframe-html\` when revising
+  functional prototype flows or their static frame counterparts.
+- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
+  into a functional prototype while preserving static mocks by default.
+- \`create-prototype-plan\`: use only when the user wants a prototype-first plan
+  and there is no existing plan text that \`/visualize-plan\` should preserve.
 - \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
-  optional \`canvas.mdx\`, optional \`.plan-state.json\`, and JSON.
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, optional \`.plan-state.json\`,
+  and JSON.
 - \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
-  artboard, annotation, component, or wireframe-node id.
+  artboard, annotation, component, prototype screen, or wireframe-node id.
 - \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
 - \`get-visual-plan\`: inspect the current structured plan, exported HTML, and
   annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed reviewer comments before coding.
+- \`get-plan-feedback\`: read unconsumed reviewer comments before coding; it
+  returns grouped threads, exact anchor details, expected resolver, and recent
+  review-event payloads so agents can act only on the comments meant for them.
 - \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
   files for repo check-in.
 
 When the user critiques a plan's look or structure, fix the renderer or this
 skill — never hand-edit one stored plan. Turn feedback into better guidance.
 
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`.
+## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and
+authenticates it in the same step (a one-time browser sign-in at setup — this is
+intended), so the first tool call does not hit an OAuth wall:
+
+\`\`\`bash
+agent-native skills add visual-plan
+\`\`\`
+
+After that, \`/visual-plan\` (and \`/ui-plan\`, \`/prototype-plan\`,
+\`/visual-questions\`, \`/visualize-plan\`) generate a plan and open the editor. Pass \`--no-connect\` to
+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.
 `;
 const BUILT_IN_APP_SKILLS = {
     assets: {
@@ -1172,6 +1959,7 @@ const BUILT_IN_APP_SKILLS = {
         extraSkills: {
             "visual-questions": VISUAL_QUESTIONS_SKILL_MD,
             "ui-plan": UI_PLAN_SKILL_MD,
+            "prototype-plan": PROTOTYPE_PLAN_SKILL_MD,
             "visualize-plan": VISUALIZE_PLAN_SKILL_MD,
         },
         manifest: normalizeAppSkillManifest({
@@ -1186,7 +1974,7 @@ const BUILT_IN_APP_SKILLS = {
             mcp: { serverName: "agent-native-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add /visual-plan, /visual-questions, /ui-plan, and /visualize-plan skills plus the Plans MCP connector. Authenticate only for hosted/account-backed sharing.",
+                setup: "Install with the Agent-Native CLI to add /visual-plan, /visual-questions, /ui-plan, /prototype-plan, and /visualize-plan skills plus the Plans MCP connector. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
@@ -1206,6 +1994,12 @@ const BUILT_IN_APP_SKILLS = {
                     path: "/plans",
                     description: "Create a UI-first Agent-Native plan with an optional top pan/zoom wireframe canvas and a refined rich document below.",
                 },
+                {
+                    id: "prototype-plan",
+                    action: "create-prototype-plan",
+                    path: "/plans",
+                    description: "Create a prototype-first Agent-Native plan with a functional live prototype above the document.",
+                },
                 {
                     id: "visualize-plan",
                     action: "visualize-plan",
@@ -1228,6 +2022,11 @@ const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "ui-plan",
                 },
+                {
+                    path: "skills/prototype-plan",
+                    visibility: "exported",
+                    exportAs: "prototype-plan",
+                },
                 {
                     path: "skills/visualize-plan",
                     visibility: "exported",
@@ -1300,6 +2099,9 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "visual-question": "visual-plans",
     "ui-plan": "visual-plans",
     "ui-plans": "visual-plans",
+    "prototype-plan": "visual-plans",
+    "prototype-plans": "visual-plans",
+    prototype: "visual-plans",
     "visualize-plan": "visual-plans",
     "visualize-plans": "visual-plans",
     "html-plan": "visual-plans",
@@ -1325,6 +2127,7 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
         "visual-plan",
         "visual-questions",
         "ui-plan",
+        "prototype-plan",
         "visualize-plan",
         "html-plan",
         "plannotate",
@@ -1495,6 +2298,7 @@ export function parseSkillsArgs(argv) {
         printJson: false,
         instructions: true,
         mcp: true,
+        connect: true,
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -1533,6 +2337,8 @@ export function parseSkillsArgs(argv) {
             out.instructions = false;
         else if (arg === "--instructions-only" || arg === "--no-mcp")
             out.mcp = false;
+        else if (arg === "--no-connect" || arg === "--skip-connect")
+            out.connect = false;
         else if (arg.startsWith("-"))
             throw new Error(`Unknown option: ${arg}`);
         else if (!out.target)
@@ -1663,6 +2469,8 @@ function dryRunInstallCommand(parsed, target) {
         args.push("--instructions-only");
     if (!parsed.instructions && parsed.mcp)
         args.push("--mcp-only");
+    if (!parsed.connect)
+        args.push("--no-connect");
     if (parsed.yes || isKnownSkill(target))
         args.push("--yes");
     return commandString("agent-native", args);
@@ -1736,6 +2544,72 @@ function withMcpUrlOverride(target, input) {
         },
     };
 }
+/**
+ * Whether we can run the interactive browser/device auth flow. CI and
+ * non-TTY shells must not block on a browser approval, so we skip the inline
+ * flow there and surface the exact `agent-native connect` command instead.
+ */
+function canRunInteractiveConnect(options) {
+    if (options.isInteractive)
+        return options.isInteractive();
+    if (process.env.AGENT_NATIVE_NO_PROMPT === "1")
+        return false;
+    if (process.env.CI === "true")
+        return false;
+    return !!process.stdin.isTTY && !!process.stdout.isTTY;
+}
+/** Build the `agent-native connect <url> --client … --scope …` command. */
+function connectCommandFor(hostedUrl, clients, scope) {
+    const args = [
+        "connect",
+        hostedUrl,
+        "--client",
+        clientArgForClients(clients),
+        "--scope",
+        scope,
+    ];
+    return commandString("agent-native", args);
+}
+/**
+ * Authenticate the freshly-registered hosted MCP connector so the user does not
+ * hit the OAuth wall on their first tool call. Reuses the existing
+ * `agent-native connect` flow (OAuth-capable clients get URL-only config plus a
+ * `/mcp` authenticate prompt; Codex / Cowork run the browser device-code flow).
+ * In non-interactive shells we skip the inline flow and return the command to
+ * run instead. Failures here are non-fatal: the connector is already registered,
+ * so the user can authenticate later.
+ */
+async function connectAfterEnsure(installTarget, clients, parsed, options) {
+    const hostedUrl = installTarget.loaded.manifest.hosted.url;
+    const authMode = installTarget.loaded.manifest.auth?.mode ?? "oauth";
+    const connectCommand = connectCommandFor(hostedUrl, clients, parsed.scope);
+    // Skills whose connector needs no auth (e.g. open/local-only) never need the
+    // connect step.
+    if (authMode === "none") {
+        return { connected: false, connectCommand: "" };
+    }
+    if (!canRunInteractiveConnect(options)) {
+        options.log?.(`Authentication skipped (non-interactive). To finish auth, run: ${connectCommand}`);
+        return { connected: false, connectCommand };
+    }
+    options.log?.(`Authenticating ${installTarget.displayName}…`);
+    try {
+        await (options.runConnect ?? runConnect)([
+            hostedUrl,
+            "--client",
+            clientArgForClients(clients),
+            "--scope",
+            parsed.scope,
+        ]);
+        return { connected: true, connectCommand: "" };
+    }
+    catch (err) {
+        // Non-fatal: the MCP connector is registered. Surface the manual command.
+        options.log?.(`Could not finish authentication automatically (${err?.message ?? err}). ` +
+            `Run it later with: ${connectCommand}`);
+        return { connected: false, connectCommand };
+    }
+}
 export async function addAgentNativeSkill(parsed, options = {}) {
     const target = parsed.target ?? "assets";
     const knownTarget = normalizeKnownSkillTarget(target);
@@ -1812,6 +2686,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const commands = [];
     const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "an-skills-add-"));
     let instructionSource;
+    let connected = false;
+    let connectCommand;
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
@@ -1853,6 +2729,17 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     confirm: true,
                     log: options.log,
                 });
+                // One-step install + authenticate: after registering a hosted MCP
+                // connector, kick off the existing connect/device-code flow so the user
+                // does not hit an OAuth wall on the first tool call. `--no-connect`
+                // opts out; non-interactive shells get the exact command to run.
+                if (parsed.connect) {
+                    const result = await connectAfterEnsure(installTarget, clients, parsed, options);
+                    connected = result.connected;
+                    connectCommand = result.connectCommand || undefined;
+                    if (connectCommand)
+                        commands.push(connectCommand);
+                }
             }
         }
         return {
@@ -1865,6 +2752,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             mcpClients: clients,
             dryRun: parsed.dryRun,
             commands,
+            connected,
+            connectCommand,
         };
     }
     finally {
@@ -1948,6 +2837,17 @@ export async function runSkills(argv, options = {}) {
             .filter((result) => result.local)
             .flatMap((result) => result.commands)),
     ];
+    const authConnected = results.some((result) => result.connected);
+    const pendingConnectCommands = [
+        ...new Set(results
+            .map((result) => result.connectCommand)
+            .filter((command) => Boolean(command))),
+    ];
+    const authLine = authConnected
+        ? "Authentication: completed."
+        : pendingConnectCommands.length
+            ? `Authentication: pending — run ${pendingConnectCommands.join(" && ")}`
+            : "";
     process.stdout.write([
         `Installed ${installedNames} skill${results.length === 1 ? "" : "s"}.`,
         skillsAgents.length
@@ -1959,6 +2859,7 @@ export async function runSkills(argv, options = {}) {
         mcpUrls.length
             ? `MCP URL${mcpUrls.length === 1 ? "" : "s"}: ${mcpUrls.join(", ")}.`
             : "",
+        authLine,
         localCommands.length ? `Local command: ${localCommands.join(", ")}.` : "",
         "Restart or reload selected agent clients if the skill is not visible yet.",
         parsed.clientExplicit