@agent-native/core 0.37.3 → 0.38.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|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`,
+ * `/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\`, \`/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: >-
@@ -205,9 +258,9 @@ 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 \`/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,9 +284,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
-  explicitly and proceed, and put anything unresolved in an open-questions block.
+  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 create visual questions from \`/visual-plan\`.
+  Otherwise state the assumption explicitly and proceed, and put anything
+  unresolved in an open-questions block.
 - **The plan is the approval gate.** After surfacing it, ask the user to review
   and approve before you write code, and name which files/areas the work touches.
   Presenting the plan and requesting sign-off is the approval step — do not ask a
@@ -244,102 +299,123 @@ direction before you implement.
 
 ## Core Workflow
 
-1. Call \`create-visual-plan\` with the title, brief, source, repo path, and
+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. 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,
+3. Compose the canvas from the kit and write the document with native blocks
+   (see the two cores below). Keep the document close to the Markdown plan the
+   agent would normally output; add diagrams, wireframes, and visual callouts
+   only where they clarify the plan. Skip the canvas 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.
-5. Apply changes with \`update-visual-plan\`, preferring targeted \`contentPatches\`.
+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.
 
 <!-- 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 +426,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 +444,66 @@ 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 on the canvas.** When the user asks for a mockup, UI state,
+loading state, prototype, layout, screen, or visual comparison, make the top
+canvas the primary home for that visual. Document blocks can explain, compare,
+or map implementation, but they should not host the primary mockup just because
+\`custom-html\`, screenshots, or prose are easier to produce. If the canvas cannot
+represent the requested fidelity, still keep a canvas artboard and call out or
+extend the needed canvas 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
@@ -391,7 +527,10 @@ 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.
 
-**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
@@ -414,41 +553,53 @@ a dedicated open-questions / needs-clarification block. Never put 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. 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 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-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-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.
@@ -466,6 +617,41 @@ props that just restates what the canvas already shows. Never produce this.
 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\`, \`/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.
 `;
@@ -487,8 +673,9 @@ comes first; implementation detail comes after the user has something concrete t
 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 \`/visual-questions\` only when the user explicitly wants
+visual intake before planning, and \`/visualize-plan\` when a text plan already
+exists.
 
 ## Plan Discipline
 
@@ -503,21 +690,27 @@ 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 create visual
+  questions from \`/ui-plan\`. 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
+5. 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
@@ -531,87 +724,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 +827,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 +845,66 @@ 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 on the canvas.** When the user asks for a mockup, UI state,
+loading state, prototype, layout, screen, or visual comparison, make the top
+canvas the primary home for that visual. Document blocks can explain, compare,
+or map implementation, but they should not host the primary mockup just because
+\`custom-html\`, screenshots, or prose are easier to produce. If the canvas cannot
+represent the requested fidelity, still keep a canvas artboard and call out or
+extend the needed canvas 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
@@ -663,7 +928,10 @@ 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.
 
-**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
@@ -686,40 +954,52 @@ a dedicated open-questions / needs-clarification block. Never put 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. 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 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-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\`,
@@ -736,13 +1016,50 @@ props that just restates what the canvas already shows. Never produce this.
 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\`, \`/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_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
 ---
@@ -767,6 +1084,9 @@ 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
 assumptions in the plan.
 
+Visual questions are an explicit intake command, not an automatic preflight for
+\`/visual-plan\` or \`/ui-plan\`.
+
 ## Workflow
 
 1. Call \`create-visual-questions\` with a clear title, brief, source, and repo
@@ -819,7 +1139,43 @@ 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\`, \`/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
@@ -874,87 +1230,99 @@ still reads like a plan, not a marketing page.
    native plan unless the user asks.
 
 <!-- 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 +1333,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 +1351,66 @@ 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 on the canvas.** When the user asks for a mockup, UI state,
+loading state, prototype, layout, screen, or visual comparison, make the top
+canvas the primary home for that visual. Document blocks can explain, compare,
+or map implementation, but they should not host the primary mockup just because
+\`custom-html\`, screenshots, or prose are easier to produce. If the canvas cannot
+represent the requested fidelity, still keep a canvas artboard and call out or
+extend the needed canvas 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
@@ -1006,7 +1434,10 @@ 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.
 
-**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
@@ -1029,34 +1460,45 @@ a dedicated open-questions / needs-clarification block. Never put 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. 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 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
@@ -1078,7 +1520,43 @@ props that just restates what the canvas already shows. Never produce this.
 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\`, \`/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: {
@@ -1495,6 +1973,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 +2012,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 +2144,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 +2219,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 +2361,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 +2404,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 +2427,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             mcpClients: clients,
             dryRun: parsed.dryRun,
             commands,
+            connected,
+            connectCommand,
         };
     }
     finally {
@@ -1948,6 +2512,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 +2534,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