@agent-native/core 0.96.0 → 0.98.0

package/dist/cli/skills.js

@@ -15,2717 +15,9 @@ import { CONTEXT_XRAY_SKILL_MD, installLocalContextXray, } from "./context-xray-
 import { CLIENTS } from "./mcp-config-writers.js";
 import { PR_VISUAL_RECAP_SETUP, writePrVisualRecapWorkflow } from "./recap.js";
 import { setupAgentSymlinks } from "./setup-agents.js";
+import { ASSETS_SKILL_MD, CANVAS_REFERENCE_MD, CONNECTION_REFERENCE_MD, CONTENT_SKILL_MD, DESIGN_EXPLORATION_SKILL_MD, DESIGN_VISUAL_EDIT_SKILL_MD, DOCUMENT_QUALITY_REFERENCE_MD, EXEMPLAR_REFERENCE_MD, HELP, LOCAL_FILES_REFERENCE_MD, VISUAL_PLANS_SKILL_MD, VISUAL_RECAP_SKILL_MD, VISUALIZE_REPO_SKILL_MD, WIREFRAME_REFERENCE_MD, } from "./skills-content/index.js";
 import { createCliTelemetry } from "./telemetry.js";
-const HELP = `npx @agent-native/core@latest skills
-
-Usage:
-  npx @agent-native/core@latest skills list
-  npx @agent-native/core@latest skills status [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
-  npx @agent-native/core@latest skills update [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
-
-Examples:
-  npx @agent-native/core@latest skills add assets
-  npx @agent-native/core@latest skills add content --mode local-files
-  npx @agent-native/core@latest skills add design-exploration
-  npx @agent-native/core@latest skills add visual-edit
-  npx @agent-native/core@latest skills add visual-plan
-  npx @agent-native/core@latest skills add visual-recap
-  npx @agent-native/core@latest skills add visualize-repo
-  npx @agent-native/core@latest skills add visual-recap --with-github-action
-  npx @agent-native/core@latest skills add visual-plan --mode local-files
-  npx @agent-native/core@latest skills add visual-plan --mode self-hosted --mcp-url https://my-plan-app.example.com
-  npx @agent-native/core@latest skills status visual-plan
-  npx @agent-native/core@latest skills update visual-plan
-  npx @agent-native/core@latest skills update scaffold --project
-  npx @agent-native/core@latest skills add visual-plan --no-connect
-  npx @agent-native/core@latest skills add context-xray --client all
-  npx @agent-native/core@latest skills add assets --client claude-code
-  npx @agent-native/core@latest skills add assets --mcp-url https://my-app.ngrok-free.dev
-  npx @agent-native/core@latest skills add ./dist/assets-skill --client codex
-  npx @agent-native/core@latest skills add BuilderIO/skills --client codex --scope project
-  npx @agent-native/core@latest skills add BuilderIO/skills --with-github-action
-
-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. Hosted installs can configure Claude Code, Codex,
-Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files
-instruction installs target the shared .agents skill path used by Codex, Pi,
-Cursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill
-path when selected. Pass --client to narrow it. Authentication reuses
-"npx @agent-native/core@latest connect": OAuth-capable clients (Claude Code,
-Cursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate
-inside that host, while Codex / Cowork run the browser device-code flow. In a
-non-interactive shell or CI the auth step is skipped and the exact
-"npx @agent-native/core@latest connect <url> --client all" command is printed instead.
-
-Running "npx @agent-native/skills@latest add ..." uses this same shared install
-flow with the broader BuilderIO skills catalog enabled. Pass --no-connect to
-register MCP where possible without authenticating (leave auth to the host or run
-"npx @agent-native/core@latest 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.
-
-When installing visual-plan, visual-recap, or visualize-repo interactively, the
-CLI asks where Plans artifacts should live: hosted Plans for shareable
-links/comments, local files for "No sharing, all local.", or a
-self-hosted/custom Plan app URL.
-Pass --mode to choose directly. Local-files mode skips MCP registration and
-auth and installs instructions that default to a no-auth block catalog fetch,
-MDX folders, and the localhost bridge viewer.
-
-When installing content with --mode local-files, the CLI installs Content
-instructions and writes or updates agent-native.json with repo-backed Markdown /
-MDX roots for docs, blog, content, and resources. Use a local Content app, Agent
-Native Desktop, or another trusted local bridge for Content actions to read and
-write those files.
-
-When installing visual-recap interactively, the CLI offers to add the optional PR
-Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
-run "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
-verify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.
-
-The status/update commands inspect copied Agent Native skill folders and refresh
-their instruction files from the current @agent-native/core package. In generated
-apps/workspaces, "skills update scaffold --project" refreshes the framework
-skills copied into the scaffold and repairs AGENTS.md / CLAUDE.md and
-.agents/skills / .claude/skills compatibility links.`;
-const ASSETS_SKILL_MD = `---
-name: assets
-description: >-
-  Use Assets for image or video generation requests, brand-safe media,
-  human picker UI, search/list/export actions, and cross-app asset selection.
-  Prefer this over generic image tools when installed.
-metadata:
-  visibility: exported
----
-
-# Assets
-
-Use the Assets app when a workflow needs reusable brand media, a human picker,
-or generated image/video assets that another app can reference by ID and URL.
-When this skill is available, route plain image-generation requests here instead
-of using a generic image generator.
-
-## Choose The Path
-
-- Use \`open-asset-picker\` when a person should browse, search, generate, and
-  select an asset in UI. Pass \`mediaType: "image"\` by default, or
-  \`mediaType: "video"\` for video libraries. When the user asks to create a
-  specific image and choose the best option, pass \`prompt\`,
-  \`autoGenerate: true\`, and \`count: 3\` so the picker opens with candidates
-  to preview and select.
-- Use unattended actions when the agent already knows what to do:
-  \`search-assets\`, \`list-assets\`, \`generate-image\`,
-  \`generate-image-batch\`, \`generate-video\`,
-  \`refresh-generation-run\`, and \`export-asset\`.
-- Use browser/deep-link fallback when the host cannot render MCP Apps inline.
-  Surface the returned picker link. If it opens in a normal browser tab, have
-  the user select an asset there and paste back the copied handoff summary.
-  Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts; do not
-  promise inline MCP App rendering there.
-  If the skill instructions are available but the MCP tool namespace has not
-  appeared yet, use the Assets browser fallback URL shape instead of switching
-  to a generic generator:
-  \`https://assets.agent-native.com/library?mediaType=image&prompt=...&autoGenerate=1&count=3\`.
-  When reporting the final selected image in Codex or Claude Code, include the
-  asset link and, if an inline preview is important, download the selected
-  \`previewUrl\`/\`downloadUrl\` to a local temp image and embed that absolute
-  local path. Remote CDN markdown images can fail to render in code-editor chat
-  surfaces.
-
-## Image And Video Workflows
-
-1. Pick or match the library with \`list-libraries\` or \`match-library\`.
-2. For images, call \`generate-image\` or \`generate-image-batch\`. Image
-   actions are synchronous: one batch call should return the finished image
-   candidates, so do not poll or regenerate unless a returned slot failed.
-3. For videos, call \`generate-video\` and poll \`refresh-generation-run\`
-   until the run completes.
-4. Preserve returned \`assetId\`, \`runId\`, \`previewUrl\`, \`downloadUrl\`,
-   media type, and dimensions so the caller can attach or embed the result.
-
-## Cross-App Use
-
-- Hosted default: connect \`https://assets.agent-native.com/_agent-native/mcp\`.
-  Do not put shared secrets in skill files.
-- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
-  running until browser authorization finishes. Stopping it early can leave the
-  browser approved but the local MCP config unwritten. Restart or reload the
-  agent client after installing or connecting if Assets tools do not appear in
-  the live session.
-- Local customization: use \`npx @agent-native/core@latest app-skill launch --local\` from an
-  Assets app-skill manifest, or pass \`--into <path>\` for editable source.
-- Do not call image/video providers directly from another app. Assets owns
-  generation, picker UI, search/list/export, and asset context.
-- If an Assets tool call returns \`Session terminated\`, \`needs auth\`, or
-  another connector/session error, do not keep retrying the tool. Stop and give
-  the user the reconnect step: in Claude Code run \`/mcp\` and choose
-  Authenticate/Reconnect for the Assets connector; from any terminal run
-  \`npx -y @agent-native/core@latest reconnect https://assets.agent-native.com\` — this
-  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
-  auth. Continue once the connector is available.
-- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
-  host-exposed Assets tools after restart/reload, or use the returned
-  browser/deep-link fallback.
-- If a batch image generation request times out in browser fallback, retry with
-  \`count: 1\` only after telling the user the multi-candidate request timed out.
-- If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
-  and token values. Never paste bearer tokens into chat or logs.
-`;
-const CONTENT_SKILL_MD = `---
-name: content
-description: >-
-  Use Content for repo-backed Markdown/MDX docs, blogs, resources, rich
-  document editing, local components, shareable copies, and Content local-file
-  workspaces. Prefer Content actions over raw filesystem writes when available.
-metadata:
-  visibility: exported
----
-
-# Content
-
-Use the Content app when a workflow is about authoring, editing, reviewing, or
-publishing Markdown/MDX documents: docs sites, blogs, resource libraries,
-marketing pages, internal notes, and local MDX components. Content gives the
-agent a document tree, a rich editor, normal document actions, and optional
-local-file source of truth.
-
-## Choose The Path
-
-- Use Content actions when the Content MCP/action tools are available:
-  \`list-documents\`, \`search-documents\`, \`get-document\`,
-  \`pull-document\`, \`create-document\`, \`edit-document\`,
-  \`update-document\`, \`delete-document\`, \`share-local-file-document\`,
-  \`list-local-component-files\`, and \`write-local-component-file\`.
-- Use \`pull-document\` or \`get-document\` before editing a page. Use
-  \`edit-document\` for precise find/replace changes and \`update-document\`
-  for full rewrites or new content.
-- In Local File Mode, Content actions read and write the repo files declared in
-  \`agent-native.json\`; SQL remains cache/history/search glue, not the source of
-  truth for those pages.
-- If Content tools are not visible and no local Content app or Desktop bridge is
-  running, treat this skill as repo-editing guidance. Edit configured
-  \`.md\`/\`.mdx\` files directly, preserve frontmatter and MDX imports, and tell
-  the user the Content action surface was not available.
-
-## Action Examples
-
-Prefer JSON input for action calls:
-
-\`\`\`bash
-pnpm action list-documents
-pnpm action get-document '{"id":"local-file:..."}'
-pnpm action edit-document '{"id":"local-file:...","find":"old copy","replace":"new copy"}'
-pnpm action update-document '{"id":"local-file:...","content":"# Updated\\n\\nBody"}'
-pnpm action share-local-file-document '{"id":"local-file:..."}'
-\`\`\`
-
-Run \`refresh-list\` after create/update/delete operations when you need the
-open Content UI sidebar to repaint immediately.
-
-## Local File Mode
-
-Install into an existing repo with:
-
-\`\`\`bash
-npx @agent-native/core@latest skills add content --mode local-files --scope project
-\`\`\`
-
-The installer copies this skill and writes or updates \`agent-native.json\` with
-Content roots for \`docs/\`, \`blog/\`, \`content/\`, and \`resources/\`, plus a
-\`components/\` folder for local MDX components. A typical manifest looks like:
-
-\`\`\`json
-{
-  "version": 1,
-  "apps": {
-    "content": {
-      "mode": "local-files",
-      "roots": [
-        { "name": "Docs", "path": "docs", "kind": "docs", "extensions": [".md", ".mdx"] },
-        { "name": "Blog", "path": "blog", "kind": "blog", "extensions": [".md", ".mdx"] },
-        { "name": "Content", "path": "content", "kind": "content", "extensions": [".md", ".mdx"] },
-        { "name": "Resources", "path": "resources", "kind": "resources", "extensions": [".md", ".mdx"] }
-      ],
-      "components": "components",
-      "extensions": "extensions",
-      "hide": ["**/_*.md", "**/_*.mdx"]
-    }
-  }
-}
-\`\`\`
-
-Local File Mode does not make the host language model local, and the hosted
-Content app cannot read private repo files by itself. File access requires a
-local Content app, Agent Native Desktop, or another trusted local bridge.
-
-## MDX And Components
-
-- Preserve frontmatter keys you do not understand. Preserve MDX imports,
-  exports, JSX, and expression props unless the user explicitly asks to change
-  them.
-- Use local components from the configured \`components\` folder. Components
-  should be PascalCase exports from \`.tsx\` files; simple editable input metadata
-  can live next to them as \`ComponentNameInputs\`.
-- Use \`list-local-component-files\` and \`write-local-component-file\` for
-  component source changes when Content tools are available. Otherwise edit the
-  component files directly like normal repo source.
-
-## Boundaries
-
-- Moving, renaming, and reordering local-file pages are not first-class Content
-  UI operations yet. Use normal file operations when the user asks for those,
-  then let Content rediscover the file tree.
-- Do not push/pull Notion, Builder.io, or other provider-backed content unless
-  the user explicitly asks for provider sync.
-- Do not paste secrets, private provider data, or credential-looking values into
-  docs, generated pages, frontmatter, examples, or local components.
-`;
-const DESIGN_EXPLORATION_SKILL_MD = `---
-name: design-exploration
-description: >-
-  Use Design for UI/UX exploration, side-by-side design directions,
-  interactive prototype previews, user selection, iteration, and design-to-code
-  handoff through the hosted Design MCP app.
-metadata:
-  visibility: exported
----
-
-# Design Exploration
-
-Use the Design app when a workflow needs visual UI exploration, prototype
-iteration, or a human-in-the-loop choice among design directions.
-
-## Choose The Path
-
-- Use \`create-design\` first to create a project shell. Do not report the
-  design as ready until it has renderable HTML.
-- For open-ended UX exploration, generate distinct, compact, complete HTML
-  directions (2-5, three by default) and call \`present-design-variants\`. Each
-  direction should be one representative screen or directional snapshot, not a
-  full app per variant. Design saves every option as a normal screen on the
-  overview board and renders an inline chat choice with one button per screen
-  name. After the user picks, delete the unchosen variant screens and continue
-  from the kept screen by first calling \`get-design-snapshot\` with that
-  screen's \`fileId\`, then calling \`edit-design\` on that same \`fileId\` in a
-  bounded single-file pass. Use \`mode: "replace-file"\` when expanding the
-  representative placeholder into the full chosen direction. Do not call
-  \`generate-design\` after a variant pick.
-- If the chat choice buttons are not available in the host, ask the user to
-  tell you the screen name they prefer. The variants are already real screens
-  on the board, so do not ask them to paste HTML or copy a generated handoff
-  summary.
-- For direct refinements to an already chosen direction, call
-  \`get-design-snapshot\`, edit from the current tuned HTML, and use
-  \`edit-design\` for surgical changes or \`mode: "replace-file"\` for a bounded
-  selected-file replacement. Use \`generate-design\` for new files only.
-- Use \`export-coding-handoff\` when the user wants to implement the chosen
-  design in a codebase.
-
-## Exploration Defaults
-
-1. Default to three variants unless the user asks for a different count
-   (\`present-design-variants\` accepts 2-5; three is the sweet spot).
-2. Make variants structurally and stylistically distinct, not just color swaps.
-3. Each variant must be a compact, complete standalone HTML document that
-   renders without a build step.
-4. For product UI redesigns, prefer cleaner hierarchy, progressive disclosure,
-   and realistic controls over decorative mockups.
-5. After \`present-design-variants\`, wait for the user's pick before
-   generating the next version. Keep the chosen screen, delete the other
-   variant screens, call \`get-design-snapshot\` with \`fileId\` for the kept
-   screen, then call \`edit-design\` on that same \`fileId\` in a bounded pass.
-   Use \`mode: "replace-file"\` when expanding the representative placeholder
-   into the full chosen direction. Do not call \`generate-design\` after a
-   variant pick. Stop after the first successful \`edit-design\` save.
-
-## Design Quality Bar
-
-Generic "AI slop" comes from letting one prompt set taste, explore, and emit code
-at once — so the model returns the training-average (Inter, an indigo/violet
-gradient, a centered hero, three rounded cards). The variant flow above exists to
-separate those jobs; use it, and hold this bar:
-
-- Before generating, name the concrete audience, the screen's primary job, and
-  the visual thesis. If the brief is vague, make a reasonable choice and state
-  it instead of producing a generic dashboard/landing-page default.
-- Refuse the defaults, and pair every "don't" with a "do" (banning Inter alone
-  just makes you reach for Roboto). Avoid Inter/Roboto/system fonts, the
-  indigo/violet slop palette (\`#6366F1\`/\`#8B5CF6\`/\`#A855F7\`) and purple-on-white
-  gradients, and centered-hero + three-icon-card layouts; instead pick a
-  distinctive font pairing, one non-default palette family with a single decisive
-  accent, and an asymmetric layout with a clear focal point.
-- Make each direction distinct in structure and behavior, not just palette.
-  Give every variant one memorable signature choice, then keep the surrounding
-  chrome disciplined. Even your creative picks converge (Space Grotesk
-  everywhere) — vary deliberately so two directions never share a fingerprint.
-- For existing products, inspect the current screen, design system, tokens, and
-  component language before inventing a new direction. Treat any drift back to a
-  default as a missing token to pin, and vary layout per screen so on-brand does
-  not become same-in-your-colors.
-- Treat copy, data, and imagery as design material. Use realistic domain
-  content and first-party/generated assets when images matter; avoid lorem
-  ipsum, vague SaaS filler, and decorative placeholder boxes.
-- Build to a quiet quality floor: responsive desktop/mobile layout, visible
-  keyboard focus, useful loading/empty/error states for app UI, and reduced
-  motion support when custom motion is present.
-- After broad generation or refinement, inspect the rendered Design surface or
-  a screenshot-capable host before calling it ready. Fix obvious hierarchy,
-  overflow, contrast, broken interaction, and placeholder-content issues first.
-
-## Cross-App Use
-
-- Hosted default: connect \`https://design.agent-native.com/_agent-native/mcp\`.
-  Do not put shared secrets in skill files.
-- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
-  running until browser authorization finishes. Stopping it early can leave the
-  browser approved but the local MCP config unwritten. Restart or reload the
-  agent client after installing or connecting if Design tools do not appear in
-  the live session.
-- Dispatch can expose Design alongside other apps. Use Design for UI/UX design
-  tasks, Assets for image/media selection, Slides for decks, and so on.
-- Keep the loop visual: surface the inline MCP App or the returned "Open
-  design" link instead of pasting large HTML blobs into chat.
-- If a Design tool call returns \`Session terminated\`, \`needs auth\`, or
-  another connector/session error, do not keep retrying the tool. Stop and give
-  the user the reconnect step: in Claude Code run \`/mcp\` and choose
-  Authenticate/Reconnect for the Design connector; from any terminal run
-  \`npx -y @agent-native/core@latest reconnect https://design.agent-native.com\` — this
-  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
-  auth. Continue once the connector is available.
-- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
-  host-exposed Design tools after restart/reload, or use the returned
-  browser/deep-link fallback.
-- If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
-  and token values. Never paste bearer tokens into chat or logs.
-`;
-const DESIGN_VISUAL_EDIT_SKILL_MD = `---
-name: visual-edit
-description: >-
-  Open a running local app in Design overview mode as URL-backed iframe screens
-  for visual editing, flow review, duplication, and route-state exploration.
-  Use when the user asks to inspect, compare, or edit a real local app visually
-  in Design.
-metadata:
-  visibility: exported
----
-
-# Visual Edit
-
-Use \`/visual-edit\` when the user wants to inspect or edit a real local app
-visually instead of generating standalone Alpine HTML. The source of truth is
-the running localhost app plus its route URLs. Design shows those routes as
-iframe-backed screens on the infinite canvas.
-
-## Core Model
-
-- Each screen is a URL-backed iframe, not copied HTML.
-- Each screen keeps URL metadata: \`connectionId\`, \`routeId\`, \`path\`,
-  \`url\`, \`bridgeUrl\`, title, and viewport size.
-- Start in Design's screen overview mode. In overview, screens are static
-  design frames; full-screen focus is for scrolling and app interaction.
-- Alt-drag duplicates a screen. For localhost screens, duplication copies the
-  iframe frame and URL metadata; change the copy's path/query for a new state.
-- Flow visualization is multiple URL states: \`/checkout?step=shipping\`,
-  \`/checkout?step=payment\`, \`/checkout?step=done\`, etc.
-- When the user gives a named flow or numbered screen list, preserve that order
-  and create one screen per URL/path. Shorthand like
-  \`localhost:1234/onboarding/1\` means
-  \`http://localhost:1234/onboarding/1\`.
-
-## Review Quality
-
-- Treat the running app as the truth. Preserve its component language, tokens,
-  route state, and real content unless the user explicitly asks for a new visual
-  direction.
-- Use multiple URL states to reveal meaningful UX moments: empty/loading/error
-  states, focused panels, modals, responsive breakpoints, and completed flow
-  steps when those matter to the review.
-- For visual edits, compare before/after at the relevant viewport sizes and
-  check key hover/focus/scroll states when the app exposes them.
-
-## Account And Sharing Model
-
-- The \`/visual-edit\` entry route can open before the viewer signs in. Public
-  \`/design/:id\` editor links can also render read-only public designs without a
-  session.
-- Prefer links returned by Design actions or \`/_agent-native/open\` deep links.
-  Do not surface URLs with \`_session=\` tokens. Query sessions are only a
-  fallback after normal cookie resolution, so an existing browser session can
-  still open the design as a different user and show "Design not found".
-- Do not attempt anonymous write actions. Bridge registration, design creation,
-  screen placement, generation, saving, and sharing are account-backed. If a
-  signed-out visitor wants to save or share, send them through the framework
-  sign-in return flow, then save or copy the design into that account before
-  opening the share dialog.
-
-## Required Local Bridge
-
-The live-edit bridge is unlocked by a shared secret (the "bridge token") that
-must match on two sides: the local bridge process, and the user's connection row
-in Design (which the browser reads to authorize \`/live-edit-bridge\`,
-\`/read-file\`, \`/write-file\`). Get them to match by letting the
-**authenticated** \`open-visual-edit\` action mint the token, then starting the
-bridge with it. This is the only ordering that works for the remote-MCP flow —
-the bridge cannot push its own token to the server without a CLI auth token, so
-the server mints instead and the bridge adopts.
-
-From the target app repo, make sure its dev server is running, then:
-
-**1. Discover routes without starting a durable bridge** (one-shot, exits):
-
-\`\`\`bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
-\`\`\`
-
-This prints the manifest (routes + capabilities). Parse it to build
-\`routeManifest\` for the next step. (Skip this if the user already gave explicit
-paths/URLs to place.)
-
-**2. Call \`open-visual-edit\`** (see Action Flow below) with NO \`bridgeToken\`.
-The server mints one, stores it on the user's connection row, copies it into the
-placed screens' metadata, and returns it to you as \`bridgeToken\`. Capture it.
-
-**3. Start the persistent bridge adopting that token** (single line; prefer the
-env var so the secret does not appear in \`ps\`):
-
-\`\`\`bash
-AGENT_NATIVE_BRIDGE_TOKEN="<bridgeToken from step 2>" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon
-\`\`\`
-
-(Equivalently, pass \`--bridge-token <token>\`.) This starts a detached bridge on
-\`http://127.0.0.1:7331\`, adopts the server-minted token — so bridge and row
-agree and live-edit authorizes with no self-registration — and stays alive after
-the command exits.
-
-For a manual health/manifest check on the running bridge:
-
-\`\`\`bash
-curl http://127.0.0.1:7331/manifest.json
-\`\`\`
-
-Only use \`--json\` for the step-1 route probe. Never use \`--json\`, \`--once\`,
-or \`--dry-run\` for the durable step-3 bridge: they print the manifest and exit,
-so Design falls back to a non-editable live iframe.
-
-## Action Flow
-
-Prefer the single authenticated \`open-visual-edit\` action. It registers or
-refreshes the localhost bridge connection, mints and stores the bridge token,
-creates or reuses a Design project, places URL-backed screens, stores the active
-visual-edit context, and navigates to overview mode in one call. This avoids
-creating a private design under a synthetic CLI user and then handing the browser
-a tokenized URL that may be shadowed by an existing session.
-
-Call it BEFORE starting the durable bridge (step 3 above): it does not contact
-the bridge, so the bridge need not be running yet, and you need its returned
-\`bridgeToken\` to start the bridge with a matching secret. Omit \`bridgeToken\`
-on the call so the server mints one.
-
-\`\`\`bash
-pnpm action open-visual-edit '{
-  "title": "Docs homepage visual edit",
-  "devServerUrl": "http://localhost:5173",
-  "bridgeUrl": "http://127.0.0.1:7331",
-  "rootPath": "/absolute/path/to/app",
-  "routeManifest": { "...": "from /manifest.json" },
-  "paths": ["/", "/pricing", "/checkout?step=payment"]
-}'
-\`\`\`
-
-The action returns \`designId\`, \`connectionId\`, \`bridgeToken\`, \`screens\`,
-\`urlPath\`, and \`openUrl\`. Keep \`designId\`/\`connectionId\` in the chat context
-for follow-ups, and pass \`bridgeToken\` to \`design connect\` (step 3) to start
-the bridge. On follow-up calls reusing an existing \`connectionId\`, the same
-token is returned (it is minted once and reused), so the running bridge stays
-valid.
-
-For a numbered flow the user describes in chat, keep the labels and order:
-
-\`\`\`bash
-pnpm action open-visual-edit '{
-  "designId": "<existing-design-id>",
-  "connectionId": "<existing-connection-id>",
-  "devServerUrl": "http://localhost:1234",
-  "routes": [
-    { "url": "localhost:1234/onboarding/1", "title": "Screen 1" },
-    { "url": "localhost:1234/onboarding/2", "title": "Screen 2" },
-    { "url": "localhost:1234/onboarding/3", "title": "Screen 3" }
-  ]
-}'
-\`\`\`
-
-For responsive follow-ups, call \`open-visual-edit\` again with the same
-\`designId\` and \`connectionId\`, plus explicit viewport dimensions:
-
-\`\`\`bash
-pnpm action open-visual-edit '{
-  "designId": "<existing-design-id>",
-  "connectionId": "<existing-connection-id>",
-  "devServerUrl": "http://localhost:5173",
-  "paths": ["/"],
-  "defaultWidth": 390,
-  "defaultHeight": 844,
-  "startX": 1600,
-  "startY": 0
-}'
-\`\`\`
-
-If no \`routes\` or \`paths\` are supplied, \`open-visual-edit\` uses every route
-from the localhost manifest.
-
-Fallback, only when \`open-visual-edit\` is unavailable:
-
-1. Register or refresh the bridge with \`connect-localhost\`, passing the
-   \`/manifest.json\` result as \`routeManifest\` and \`capabilities\`.
-2. Create or reuse a Design project with \`create-design\`.
-3. Place URL-backed screens with \`add-localhost-screens\`.
-4. Navigate to overview mode with \`navigate\`.
-
-## Open The Design Surface
-
-- Use the \`link\`, \`deepLink\`, or MCP App embed returned by Design actions so
-  the user sees the canvas. In Codex Desktop or VS Code, prefer opening that
-  Design URL in the available preview/webview panel; otherwise surface the
-  "Open design" link.
-- Return or open the \`openUrl\` / action link, not a hand-built
-  \`/design/:id?_session=...\` URL.
-- If the user is working in VS Code, the Agent Native extension can open the
-  same URL via
-  \`vscode://builder.agent-native/open?url=<encoded-design-url>\`. Its
-  \`Agent Native: Open Design Canvas\` command also starts the local bridge and
-  opens hosted Design in the VS Code side panel.
-- After \`add-localhost-screens\`, confirm the Design editor is in overview mode
-  with the requested URL-backed frames visible. Do not stop at "screens added"
-  when the user asked to inspect or edit visually.
-
-## Editing URLs
-
-Keep localhost screens as URL files plus \`screenMetadata[fileId]\`. Do not
-replace them with copied \`srcdoc\` HTML unless the user explicitly asks for a
-frozen snapshot. To change a state, rerun \`add-localhost-screens\` with the new
-path/query or duplicate the screen and update the copy's URL metadata.
-
-## React Source Writeback
-
-- Use compiler/debug provenance (project-relative file, line, column,
-  component, and runtime multiplicity) to locate React/TSX source. Treat it as
-  evidence, not as permission for a generic AST structural transform.
-- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
-  \`.map()\` instances, shared components, and cross-file changes go through the
-  coding agent with exact subject/target anchors and their runtime
-  relationship.
-- Before each write, read the file and pass its exact \`versionHash\` to
-  \`write-local-file\` with \`requireExpectedVersionHash: true\`; on conflict,
-  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms
-  the result. Human write consent remains mandatory and agents cannot grant it.
-
-## Verification
-
-- \`list-localhost-connections\` returns the expected connection and routes.
-- The Design editor opens in overview mode.
-- Every requested screen renders the intended localhost URL.
-- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
-`;
-/**
- * Setup/auth block for the `/visual-plan` skill. Interpolated into
- * `VISUAL_PLANS_SKILL_MD` below so the install + one-step authenticate
- * instructions are single-sourced. The materialized SKILL.md copies under
- * `templates/plan/.agents/skills/*`, top-level `skills/*`, and
- * `.agents/skills/*` are guarded byte-identical by `skills.sync.spec.ts`.
- */
-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 runs
-auth/setup for the selected local client(s) in the same step (a one-time browser
-sign-in at setup — this is intended), so the first tool call in that client does
-not hit an OAuth wall:
-
-\`\`\`bash
-npx @agent-native/core@latest skills add visual-plans
-\`\`\`
-
-After that, \`/visual-plan\`, \`/visual-recap\`, and \`/visualize-repo\` are the
-installed slash commands. If you only need one command, use
-\`skills add visual-plan\`, \`skills add visual-recap\`, or
-\`skills add visualize-repo\` instead. The other planning modes
-(\`create-ui-plan\`, \`create-prototype-plan\`, \`create-plan-design\`,
-\`create-visual-questions\`) are MCP tools reachable from \`/visual-plan\`, not
-separate slash commands. Pass \`--no-connect\` to register the connector without
-authenticating, then run
-\`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
-whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
-loading are per client config/session.
-
-**Local-only / text installs.** If the user wants no sharing and all local files,
-install with \`--mode local-files\`:
-
-\`\`\`bash
-npx @agent-native/core@latest skills add visual-plans --mode local-files
-\`\`\`
-
-This mode does not register the Plan MCP connector. Before authoring structured
-MDX, fetch the no-auth, schema-only block catalog with
-\`npx @agent-native/core@latest plan blocks --out plan-blocks.md\`, read that file,
-write the MDX folder locally, run \`plan local check\`, then run \`plan local serve\`.
-For repo-wide visual docs, run
-\`npx @agent-native/core@latest visualize-repo --open\` to create/update
-\`agent-native.json\`, seed \`.agent-native/visual-docs/repo-overview\`, and open
-the local bridge.
-Plain text skill
-installs (Vercel Skills CLI, copied GitHub files, etc.) can follow that same
-local flow if \`@agent-native/core\` is available. Text alone cannot register
-MCP tools; hosted/shareable Plans still need the Agent-Native CLI
-install/reconnect step above.
-
-**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 no-account, no-DB plan storage, use local-files mode and the local bridge
-command. The optional \`plan blocks\` lookup reads only public schema metadata.
-If network access is unavailable, use the bundled references and a local Plan
-app/runtime for validation.
-
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. Stop and give the user the reconnect step for the
-client they are using: Codex/Codex Desktop should run
-\`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
-and start a new Codex session; Claude Code should run \`/mcp\` and choose
-Authenticate/Reconnect for the plan connector, or run the reconnect command with
-\`--client claude-code\` and restart Claude. To refresh every local client config
-that already has the Plan entry, use \`--client all\`, then restart/reload each
-client. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by
-URL regardless of connector name. Never reinstall from scratch just to fix auth.
-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.`;
-// Single-source shared cores. Each partial is a heading-less BODY string that
-// begins and ends with its own SHARED-CORE marker comment, so the marker-region
-// sync guard can extract and compare it across the skills that consume it. The
-// skill constants below interpolate these partials at module-eval time; the
-// distributed artifact stays a flat string, so distribution is unchanged.
-//
-// Consumers:
-//   WIREFRAME_QUALITY_CORE  — visual-plan, visual-recap (surface-agnostic)
-//   CANVAS_SURFACE_CORE     — visual-plan modes (canvas/artboard mechanics)
-//   DOCUMENT_QUALITY_CORE   — visual-plan
-//   EXEMPLAR_CORE           — visual-plan
-// Surface-agnostic HTML wireframe quality rules. Applies equally to a standalone
-// WireframeBlock/<Screen> (visual-recap) and to a canvas artboard (visual-plan).
-// Do not put canvas/artboard placement mechanics here.
-const WIREFRAME_QUALITY_CORE = `<!-- SHARED-CORE:wireframe-quality START -->
-
-**A wireframe is an HTML mockup. The renderer owns the look; you write the
-content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
-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 or any
-width/height/coordinates. You write real HTML layout and real product
-content; the renderer styles and roughens it.
-
-**A wireframe block's data is an HTML screen plus a surface:**
-
-\`\`\`json
-{
-  "surface": "browser",
-  "html": "<div style=\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\"><h1>Sign in</h1><p class=\\"wf-muted\\">Use your work email to continue.</p><div class=\\"wf-card\\" style=\\"display:flex;flex-direction:column;gap:10px\\"><label>Email<input value=\\"jane@acme.co\\" /></label><label>Password<input value=\\"••••••••\\" /></label><label style=\\"display:flex;align-items:center;gap:8px\\"><input type=\\"checkbox\\" checked /> Remember me</label><button class=\\"primary\\">Sign in</button></div><a href=\\"#\\">Forgot password?</a></div>"
-}
-\`\`\`
-
-**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
-(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
-are auto-themed — no classes needed. Helper classes carry the rest:
-
-- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
-- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
-  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
-- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
-- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
-  primary button.
-
-**No decorative shadows around mockups.** Do not put \`box-shadow\`, \`filter:
-drop-shadow(...)\`, Tailwind \`shadow-*\` classes, or other fake depth effects on a
-wireframe frame, root container, \`.wf-card\` / \`.wf-box\`, or canvas artboard.
-Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
-and annotations for separation. Only show a shadow when the real product UI
-already has that shadow and it is essential to the change being reviewed.
-
-**Use renderer icons, not visible icon words.** For icon-only buttons or leading
-icons inside fields, chips, menu items, and toolbars, write an empty marker such
-as \`<span data-icon="mail" aria-label="Email"></span>\` or
-\`<i data-icon="lock"></i>\`. The renderer replaces it with a Tabler-style SVG and
-the \`.wf-icon\` class sizes it to the surrounding text. Supported names and
-aliases: \`mail\`/\`email\`, \`lock\`/\`password\`, \`search\`, \`plus\`/\`add\`, \`x\`/\`close\`,
-\`check\`, \`chevronDown\`, \`chevronUp\`, \`chevronLeft\`, \`chevronRight\`, \`dots\`/\`more\`,
-\`chevron\`/\`caret\`/\`dropdown\` (down chevron), \`user\`, \`settings\`, \`calendar\`,
-\`bell\`, \`send\`, \`edit\`, \`arrowLeft\`, and \`arrowRight\`. Do not put visible words
-like "email", "lock", "search", "chevron", or "more" where the product UI would
-show an icon; use text only when it is a real label a user would read.
-
-**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\` (container 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.
-
-**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
-\`bg-white\`, \`bg-zinc-50\`, \`bg-slate-950\`, \`text-zinc-950\`,
-\`text-slate-400\`, \`border-zinc-200\`, \`hover:bg-slate-800\`, \`shadow-xl\`,
-or arbitrary color utilities like \`bg-[#fff]\` leak the host app's CSS into the
-mockup and can make dark-mode canvas frames unreadable. Use bare semantic
-elements, \`.wf-*\` helper classes, and \`--wf-*\` color tokens instead. Before
-publishing, scan every wireframe \`class\` and \`style\` attribute: if a class sets
-background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
-or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
-are still discouraged; inline flex/grid styles are safer and easier to review.
-
-**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
-\`.wf-*\` primitives, controls, and inline border dividers by default. Do not add
-\`data-rough\` to broad root wrappers, dialog shells, page panels, grid cells, or
-nested containers unless that single container is the visual point. Use
-\`data-rough\` only for a deliberate one-off shape. If a mockup starts looking
-like stacked/overlapping sketch lines, remove rough targets from parent
-containers and let backgrounds plus spacing separate the surfaces.
-
-**Use literal CSS lengths for spacing.** The \`--wf-*\` tokens are for colors and
-renderer-owned visual styling, not layout spacing. Do not use guessed spacing
-tokens such as \`var(--wf-space-4)\`, Tailwind spacing classes, or theme spacing
-variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
-padding collapses and content hugs the border. Use explicit CSS lengths for
-layout: \`padding:16px\`, \`gap:12px\`, \`margin-top:18px\`, \`minmax(0,1fr)\`.
-
-**Lay out with inline \`style\` flex/grid.** You write the real layout —
-\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
-renderer never repositions anything. Compose the actual product: reproduce the
-current screen, then show the modification. Real labels, real counts, real dates,
-real button text grounded in the screen you read; not lorem or gray bars.
-
-**Surface presets — match the real footprint, never default to desktop+mobile.**
-Pick the \`surface\` that matches what the user will actually see:
-
-- \`browser\`: a web page that needs a browser chrome frame around it.
-- \`desktop\`: a full desktop app page or app shell.
-- \`mobile\`: a phone screen, only when the work is genuinely mobile.
-- \`popover\`: a small floating menu, dropdown, or inline popover.
-- \`panel\`: a side panel, inspector, or sidebar widget.
-
-A sidebar popover renders as a small surface, not a desktop page and a phone
-frame. Do not emit \`desktop\` + \`mobile\` variants unless responsive behavior
-actually changes the layout. For a component or widget, show one broader
-app-context frame only when placement affects understanding, then the focused
-component states.
-
-**Model the actual component shell for small surfaces.** A rendered UI change
-belongs in a wireframe; reserve \`diagram\` for architecture, dependency, state,
-or data-flow relationships. Popovers, dropdown menus, command palettes, and
-context menus use \`surface: "popover"\` unless the surrounding page placement is
-the point of the change. Dialogs, sheets, inspectors, sidebars, and long
-property panels use the matching \`panel\` / \`desktop\` surface as appropriate.
-Show the real chrome: trigger or anchor when it matters, title/header row,
-top-right actions, separators, fields, options, selected states, body content,
-and footer actions that are visible in the workflow.
-
-**Modify, don't redesign.** When the task changes an existing screen, reproduce
-the current screen's real layout and footprint FIRST, then change only the delta
-and call it out with a single annotation. Do not restack the page into a new
-layout. For net-new surfaces, compose from the real app shell. Inspect the
-actual app components before drawing an existing product: sidebar density,
-toolbar actions, overflow menus, property panels, and framework chrome should
-match the product unless the plan intentionally changes them.
-
-**Keep product screens pure.** A product wireframe shows the app state a user
-would actually see. Do not embed file contracts, architecture arrows, repo pills,
-mode explanations, or implementation callouts inside the screen just to explain
-the plan. Put those in canvas annotations, a separate diagram, or the document
-body. Secondary UI such as properties, history, sync, export, or agent controls
-should appear where the real product would put them: an overflow popover, sheet,
-panel, or separate framework sidebar state, not a generic permanent right
-inspector unless that inspector is the actual design.
-
-**Classify mockup scope before implementation.** Before turning a plan mockup
-into source code, decide whether each artboard represents the whole page/app
-shell, a route body inside an existing shell, or a component/sub-surface. If an
-artboard includes navigation, sidebars, auth banners, or a signup/login form,
-map those pieces to the real shared shell/auth components instead of nesting the
-entire mockup inside the current page. When a mockup references the product's
-standard signup/login page, find and reuse that existing implementation; do not
-approximate it from the wireframe.
-
-**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
-popover, menu, dialog, toast), show the full screen once, then add a small
-separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
-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.
-
-**Editing an existing mockup.** In hosted mode, 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. In local-files privacy mode, do not call
-hosted Plan tools; edit the local MDX source directly and rerun the local
-check/serve or verify command for \`<plan-dir>\`.
-
-**Choose the outer frame deliberately.** Wireframe and diagram data accept
-\`frame: "auto" | "show" | "hide"\` in block data (\`<Screen frame="hide">\` in
-MDX wireframes, \`<Diagram frame="hide">\` for MDX diagrams). Leave it unset or
-\`auto\` when the host context should decide: Plan and recap surfaces default to a
-drawn outer frame; docs surfaces default to no outer frame. Use \`show\` for
-standalone product screens, before/after recap comparisons, screenshot-like
-artifacts, and visuals that need containment from surrounding prose. Use \`hide\`
-when a docs page, tab, column, card, canvas artboard, or the visual's own
-internal chrome already supplies the boundary. Do not use \`hide\` to compensate
-for cramped content; fix the layout instead.
-
-**Inner padding and borders still matter.** Always wrap HTML wireframe content
-in a root container with real inner padding before drawing cards, fields, pills,
-labels, or controls. Use at least 14-16px of padding, \`box-sizing: border-box\`,
-\`height: 100%\`, and \`gap\` between child rows on the root node itself so the
-first row never sits flush against the screen edge. Do not rely on padding on a
-nested page section as the first visible inset; the outermost element must
-create the breathing room. Keep text away from borders: every container, field,
-button, menu item, and annotation needs enough padding and line-height to read
-cleanly in the rendered Plan view.
-
-**For feature-cloud or abundance visuals, optimize the composition over line-by-line
-reading.** Some marketing/product sections need to feel like a large surface area
-of capability rather than a precise app workflow. In those cases, use one padded
-root with a short headline and a dense, aesthetic cloud of short feature labels,
-chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
-and let many labels be glanceable rather than individually essential. Do not
-force dozens of features into equal cards with long wrapped sentences; that
-usually creates a messy unreadable mockup.
-
-**Lay out children safely so they never collide.** Use HTML flex/grid with
-\`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute
-positioning, or fixed child widths that can collide when the renderer switches
-between light/dark, sketch/clean, or different zoom levels.
-
-**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
-breadcrumbs, chip/filter rows, branch and file names, file chips, and code
-filenames — any deliberately single-line row — do not let long text wrap. Put
-\`white-space: nowrap\` on the row (and \`overflow: hidden; text-overflow: ellipsis\`
-on the individual labels that can grow), so the wireframe demonstrates the actual
-layout behavior instead of producing ugly stacked or vertical text. Use
-horizontally scrollable or clipped rails for overflow.
-
-**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
-
-**Persistent chrome bars span the full frame width.** Top bars, app headers,
-toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
-Lay each one out as a single flex row that fills the frame
-(\`style="display:flex;align-items:center;width:100%"\`) and push trailing actions
-to the right edge with a flex spacer (\`<div style="flex:1"></div>\`) between the
-leading group and the trailing group — never center a bar inside a narrow,
-centered block, and never let it collapse to the width of its contents. In a
-Before/After pair the bar stays full-width in BOTH states even when one state has
-fewer controls; the spacer absorbs the difference so the remaining controls hold
-their edge alignment instead of sliding to the center.
-
-**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
-any persistent bottom action row, make the frame itself a flex column at
-\`height:100%\` (\`style="display:flex;flex-direction:column;height:100%"\`), give the
-scrolling body \`flex:1\` so it absorbs the slack, and place the bar as the LAST
-child of the frame (or set \`margin-top:auto\` on it). The bar then sits flush at
-the bottom of the surface instead of floating directly under the content with an
-empty band beneath it.
-
-**Before / after must be comparable.** When showing a state change, preserve the
-unchanged controls in both states so the reviewer can see exactly what moved or
-appeared; do not show an added control as a generic box floating elsewhere in
-the surface. Place the new/changed affordance where the implementation puts it —
-for example, a new \`Edit with AI\` action in a popover header belongs in the
-top-right header slot, aligned with the title, not in the body or footer. Use
-the same frame size, scale, outer padding, border radius, and visual density on
-both sides unless the change itself alters those properties, and let the frame
-height fit the content rather than leaving a tall empty lower half.
-
-**Name the states with the column header, never inside the frame.** For
-document-body wireframes (recaps), put the two
-states in a \`columns\` block and set each column's \`label\` to \`Before\` and
-\`After\` — the renderer draws that label as an \`h4\` heading above each frame. Do
-NOT bake a \`Before\`/\`After\` pill, title, or heading into the wireframe \`html\`: a
-label placed inside reads as part of the product UI, lands in a random corner,
-and clutters the comparison. The column header is the one and only place the
-state name belongs. On a canvas, place the two state artboards as neighbors with
-frame labels — never encode Before/After inside the html.
-
-**Let the surface choose side-by-side vs. stacked.** For document-body
-wireframes (recaps), the \`columns\` renderer lays
-narrow surfaces (\`mobile\`, \`popover\`, \`panel\`) out side by side, and
-automatically stacks wide surfaces (\`desktop\`, \`browser\`) vertically at full
-document width so a large frame is never crushed into a half-width column and
-cropped. Author both wireframes with the real \`surface\` and the matching
-\`Before\`/\`After\` column labels; do not hand-stack the pair into separate
-top-level wireframes or duplicate the state name as body content.
-
-**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>
-\`\`\`
-
-<!-- SHARED-CORE:wireframe-quality END -->`;
-// Progressive-disclosure reference file. `WIREFRAME_QUALITY_CORE` is the single
-// source of truth for HTML wireframe quality; it is materialized verbatim into a
-// sibling `references/wireframe.md` in EVERY plan skill dir (visual-plan and
-// visual-recap), instead of being interpolated inline into each SKILL.md body.
-// The SKILL.md bodies carry only `WIREFRAME_REFERENCE_POINTER`, which tells the
-// agent to read this file before authoring any wireframe. Keeping the reference
-// body byte-identical to the core (markers included) lets the sync guard assert
-// the on-disk copies never drift from the canonical constant.
-export const WIREFRAME_REFERENCE_MD = `# HTML wireframe quality — single source of truth
-
-This file is the canonical quality bar for HTML wireframes / \`<Screen>\` /
-\`WireframeBlock\` content, shared word for word by \`/visual-plan\` and
-\`/visual-recap\`. Read it in full before authoring ANY wireframe; do not
-author wireframes from memory or paraphrase these rules per command.
-
-${WIREFRAME_QUALITY_CORE}
-`;
-// Short pointer that replaces the inline wireframe-quality core in each SKILL.md
-// body. Authoring quality lives in the sibling reference file so the SKILL.md
-// stays lean (progressive disclosure); the agent loads the detail on demand.
-const WIREFRAME_REFERENCE_POINTER = `UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
-pinned bottom bars, real product content, before/after comparability, the right
-\`surface\` preset, \`--wf-*\` tokens instead of hex, and no \`<html>\`/\`<style>\`/font
-tags. Before authoring ANY wireframe / \`<Screen>\` / \`WireframeBlock\`, READ
-\`references/wireframe.md\` in this skill directory — it is the single source of
-truth for HTML wireframe quality, shared word for word with \`/visual-plan\`
-and \`/visual-recap\`. Do not author wireframes from memory.`;
-// Canvas/artboard placement mechanics. Used only by visual-plan modes
-// (visual-recap renders standalone wireframes, not a canvas).
-const CANVAS_SURFACE_CORE = `<!-- SHARED-CORE:canvas-surface START -->
-
-**The coordinate rule.** The \`surface\` locks each artboard's footprint and
-aspect — never set artboard width/height and never use coordinates inside the
-wireframe HTML; board-level artboard \`x\`/\`y\` IS allowed when it creates clear
-lanes. Let canvas auto-placement handle simple one-row boards.
-
-**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
-desktop frames plus compact \`mobile\`, \`popover\`, or \`panel\` surfaces, do not put
-everything in one horizontal strip. Use board-level artboard \`x\`/\`y\` to reserve
-lanes with generous empty space: main flow on one row, compact surfaces in their
-own column or row, and loading/error states in a lower row. Keep at least 96px
-between rendered artboard rectangles plus room for annotation gutters; when a
-broad browser/desktop frame sits beside a compact panel/popover, leave at least
-160px so frame borders, labels, and hover controls never touch. Connect only
-neighboring steps; never draw a long connector that skips across unrelated
-frames. Connector labels must sit in open canvas space. If the label would touch
-or cross either artboard, remove the label and explain the transition with a
-nearby annotation instead. Before handoff, inspect the top canvas at default zoom
-and move any frame whose label, connector, or annotation crosses another frame.
-
-**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. \`browser\` frames occupy roughly 700 × 600 board units; \`desktop\` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:
-
-- x-gap between \`browser\` frames: **≥ 1100** (700-unit frame + 400-unit gutter)
-- x-gap between \`desktop\` frames: **≥ 1300** (900-unit frame + 400-unit gutter)
-- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)
-
-When in doubt, use larger values — the canvas auto-zooms to fit everything.
-
-**Canvas annotations are designer notes on the artboard.** When a top canvas is
-present, sprinkle design-review notes near the frames they explain: a short
-heading, supporting text, and bullets — plain text layers, never bordered or
-shadowed cards, and never a box around a frame. The renderer spaces notes away
-from frames, so place each note by the frame it describes. Use an arrow only to
-point at one specific control or transition; for a broad frame-level note, write
-text beside the frame with no connector. Connectors are for real sequences only —
-never fake "Step 1 → Step 2" lines between independent states.
-
-**Do not create overlapping annotations.** Anchor each ordinary note to the
-frame it explains with \`targetId\` + \`placement\` (top/right/bottom/left), and
-omit \`type\` or use \`type: "note"\`. The renderer parks notes in a gutter beside
-the frame and lays them out automatically. Do not use \`type: "callout"\`,
-\`type: "text"\`, \`type: "arrow"\`, x/y, or points for ordinary notes; those are
-freeform review-markup layers and must be reserved for intentional markup in
-open canvas space. Reserve arrows for a note that must point at one specific
-control inside a frame; a note that simply sits beside its frame needs no arrow.
-
-**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted \`contentPatches\`
-(for example \`patch-wireframe-html\`, \`patch-diagram-html\`, \`update-block\`,
-\`replace-blocks\`, \`update-canvas-annotation\`) rather
-than regenerating the whole plan. \`contentPatches\` are part of the public MCP
-action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
-edits. If an agent is working from exported source files, use
-\`read-visual-plan-source\` / \`patch-visual-plan-source\`: \`plan.mdx\` holds
-frontmatter plus markdown/document blocks, \`canvas.mdx\` holds
-\`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\`, and the
-patch action normalizes the MDX back into the same JSON runtime model. JSON is
-the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
-In the browser, humans edit \`rich-text\` prose inline; agents should still use
-\`update-rich-text\` content patches or source patches for prose, and use
-comments/structured patches for canvas, artboard, wireframe, and diagram edits.
-Never send a partial top-level \`content\` object as a shortcut to add a canvas,
-frame, or block: \`content\` is a full structured replacement, so omitted blocks
-or surfaces can disappear. If a full replacement is truly unavoidable, read the
-complete source/JSON first, include every existing block and surface in the new
-payload, and verify the source/export immediately after the update.
-
-**Never emit a titled artboard with no interior wireframe content.** Every artboard
-you place on the canvas must carry an \`html\` wireframe or reference a wireframe
-block via \`blockId\`; when using \`blockId\`, the referenced \`wireframe\` /
-\`legacy-wireframe\` block must remain in the plan. If you remove a duplicate
-wireframe from the document body, first move its \`data\` inline onto the
-corresponding \`content.canvas.frames[*].wireframe\` / \`legacyWireframe\`. A
-label-only frame or a frame pointing at a deleted block renders empty and is
-rejected at parse time. If you only have a title, write it as a section header or
-annotation, not an empty artboard.
-
-**UI mockups belong in the top visual review area.** Static UI/product visuals
-live on the canvas; multi-step UI flows get both canvas wireframes and a
-prototype. When the user asks for a mockup, UI state, loading state, layout,
-screen, or visual comparison, make the canvas the primary home for that static
-visual. When the user asks for a prototype or the plan contains a sequence the
-reviewer must feel, keep the canvas artboards and add \`content.prototype\` so the
-top surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay
-inline in the document (the SKILL.md Visual Surface Choice section owns that
-rule) unless the user explicitly asks for a spatial board. Document blocks
-can explain, compare, or map implementation, but they should not host the
-primary UI mockup or prototype just because \`custom-html\`, screenshots, or prose
-are easier to produce. If the canvas/prototype surface cannot represent the
-requested UI fidelity, still keep the closest top-surface representation and
-call out or extend the needed renderer capability. A skeleton/loading mockup
-also lives in a canvas artboard — never move a mockup out of the canvas.
-
-**Storyboards are canvas artifacts, not document diagrams.** When the requested
-output is a product flow, onboarding journey, "light storyboard", or canvas
-wireframe, author the flow as multiple top-canvas artboards with real screen
-content and neighboring connectors. Keep document-body \`diagram\` blocks for
-architecture and mechanics that are not themselves user-visible screens. A
-storyboard made from a single inline HTML diagram is the wrong surface.
-
-For abstract product concepts, use the canvas to create the first "I get it"
-moment: one real app state near the top showing how the concept appears to a
-user, followed by separate annotations or diagrams for mechanics. Do not make
-the first artboard a hybrid of app UI and architecture notes; the app screen
-should be inspectable as product UI on its own.
-
-**Legacy kit tree.** Older plans set a \`screen\` array of \`{ el, ...props }\` kit
-nodes instead of \`html\`; the renderer still accepts and displays it so saved
-plans round-trip, but new plans emit \`html\`. Do not author fresh kit-tree
-screens, and do not put nested kit components such as \`<FrameScreen>\`, \`<Card>\`,
-\`<Row>\`, \`<Title>\`, or \`<Btn>\` inside a canvas \`<Screen>\`. A new canvas artboard
-with kit-tree children is a defect: replace it with
-\`<Screen surface="..." html={...} />\` using the HTML wireframe rules. The HTML
-path is the one that gets the renderer-owned surface sizing, theme tokens,
-sketch/clean toggle, and safe text layout used by good document-body
-wireframes. Likewise, old or imported plans may carry coordinate-based regions
-or free-float x/y on notes; those are legacy escape hatches the renderer still
-shows but you must never produce. The gutter parks notes by \`targetId\` +
-\`placement\`, and the coordinate rule at the top of this file governs all
-new-plan placement.
-
-<!-- SHARED-CORE:canvas-surface END -->`;
-const DOCUMENT_QUALITY_CORE = `<!-- SHARED-CORE:document-quality START -->
-
-**The document is a serious technical plan, not marketing.** Write it the way a
-strong Claude or Codex implementation plan reads: outcome-first, prose-first,
-self-contained, and specific. State the objective and what "done" means, the
-scope and non-goals, the proposed approach with the key decisions and their
-rationale, ordered steps that name real files, symbols, actions, and data
-shapes, the risks, and a closing verification step (tests, build, or a checkable
-behavior). Replace vague prose with specifics; never ship a step like "make it
-work." No hero art, gradients, logos, nav bars, slogans, value props, giant
-landing-page headings, or marketing cards unless the user explicitly asks.
-
-**Every published plan must stand alone.** Even when the agent is revising an
-existing plan, the output is a plan to do the work, not a changelog of the
-conversation. Do not write phrases like "preserve the previous plan", "do not
-drop the old idea", "as discussed above", "this revision", "unlike the prior
-version", or "correction from the earlier plan". Fold the right decisions into
-the plan as normal objective, architecture, scope, and roadmap prose. A reviewer
-who opens the plan from a link with no chat history should understand it. Avoid
-negative framing that only makes sense against absent context ("not the old
-mode", "not just X") unless the contrast is defined in the plan and genuinely
-helps; state the positive model directly.
-
-**Make abstract plans instantly legible.** If the idea is broad, strategic, or
-intended for a third-party reviewer, put one concrete product snapshot near the
-top before dense architecture, mode tables, manifests, or roadmaps. For
-UI-capable concepts, that snapshot is usually a top-canvas app state plus a
-short paragraph that says what the user sees and what changes under the hood.
-Then put mechanics, data flow, sync boundaries, and implementation detail in
-separate diagrams or document sections.
-
-**Preserve the user's level of abstraction.** A motivating use case is not
-automatically the architecture. When the prompt describes a broader framework,
-product mode, or reusable primitive, separate the reusable core from specific
-apps, providers, customers, scripts, or launch examples. Use the concrete
-example to make the plan understandable, then make clear which parts are core,
-which are app-specific adapters, and which are future examples.
-
-**When top visuals exist, they and the document never duplicate each other.**
-For UI work, the UI story lives in the top visual surface: canvas artboards for
-static inspection, plus prototype tabs when the flow should be functional. The
-document carries the technical depth the visuals cannot show — concrete
-file/symbol maps, API and data contracts, code snippets, migration or
-implementation phases, risks, and validation. For architecture/code reviews,
-invert that: the document is the visual surface, and each recommendation
-carries its own nearby inline \`diagram\` / \`data-model\` block plus file
-evidence (the \`diagram\` bullet below owns how to author those diagrams).
-Repeat a wireframe in the document only for a genuinely new detail view or
-comparison. Skip the visual surface entirely for non-visual work and write a
-clean rich document. For a simple binary UI visual choice, show the two
-directions in the canvas only; do not repeat the same options as body
-wireframes or prose. Put the actual choice in the bottom "Open Questions" form.
-
-**Use the right block, and make it carry substance.** For the authoritative,
-machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
-— 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.
-- \`annotated-code\` for the file map: when a load-bearing file is worth
-  highlighting, prefer the annotated walkthrough over a bare \`code\` block — carry
-  the real, syntax-highlighted code AND anchor short margin notes to the lines
-  that actually change (the new action, the changed schema, the wiring point), so
-  the reader sees what matters and why instead of code for code's sake. Each
-  annotation is \`{ lines: "12" | "12-18"; label?; note }\`; keep a few high-signal
-  notes per file, not one per line. Highlight only the files worth reading; never
-  an exhaustive list of every touched file, and never a prose-only description of
-  a file. Drop to a plain \`code\` block only for a throwaway snippet with nothing
-  to call out. When more than one file matters, group the blocks in a vertical
-  \`tabs\` block (the standard tab primitive) rather than a bespoke container. If
-  the exact code is unknown, show the smallest plausible planned shape or a
-  commented stub naming what to fill in. (\`code-tabs\` and \`implementation-map\`
-  are legacy: their renderers stay for old plans, but do not author new ones.)
-- For a decision: if the reviewer must still pick between a genuinely-open
-  either/or, put it in the bottom Open Questions \`question-form\` as a \`single\`
-  question — one option per real alternative, each with a short detail and
-  \`recommended: true\` on the one you would choose; do not also restate the same
-  choice elsewhere. If you have already committed to an approach, state it as
-  settled prose or a \`callout\` with \`tone="decision"\`, optionally with a
-  \`columns\` block for a side-by-side comparison of the options you weighed — not
-  as a confusing mid-document form for a question you have already answered.
-- \`columns\` for side-by-side before/after or current/target comparisons where
-  each side needs real nested blocks; label the columns clearly and avoid
-  stacking comparison blocks vertically when parallel reading is the point.
-- \`diagram\` for two-dimensional architecture, dependency, data-flow, or state
-  relationships, only when it clarifies something real. Prefer standard
-  two-dimensional layouts — paired before/after panels, layered diagrams,
-  swimlanes, dependency maps, matrices, or grouped regions; do not default to
-  left-to-right chains, and use a line only when the relationship is truly a
-  sequence. Do not use a body \`diagram\` as the primary artifact for a requested
-  product canvas, light storyboard, UI flow, screen flow, or wireframe; those
-  belong in the top canvas as artboards with \`Screen\` wireframes first. Use
-  diagrams below that canvas only for architecture, data flow, or implementation
-  mechanics. For architecture/code
-  diagrams, prefer \`data.html\` / \`data.css\` with semantic HTML and inline SVG so
-  the diagram can use panels, layers, matrices, arrows, annotations, and
-  responsive layout directly. Author diagram HTML with renderer-owned primitives
-  like \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
-  \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; they map to the plan's
-  Tailwind theme variables through \`--wf-ink\`, \`--wf-muted\`, \`--wf-line\`,
-  \`--wf-paper\`, \`--wf-card\`, \`--wf-accent\`, \`--wf-accent-soft\`, \`--wf-warn\`, and
-  \`--wf-ok\`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
-  set \`font-family\` and do not hard-code hex, rgb, or hsl colors in diagram HTML
-  or CSS. Choose the outer \`frame\` intentionally: use \`show\` when the diagram
-  stands alone in a recap, comparison, or prose section; use \`hide\` when the
-  diagram sits inside docs chrome, columns, tabs, cards, a canvas surface, or
-  already has visible \`.diagram-panel\` / \`.diagram-box\` structure. Leave room
-  for the sketch font: keep labels short, give nodes generous width, and place
-  boundary/annotation labels in unused space instead of over nodes; labels must
-  not overlap nodes, connectors, or each other. For small text/SVG changes to an
-  existing HTML diagram, use \`patch-diagram-html\` with a unique
-  \`find\`/\`replace\` snippet instead of resending the whole \`data.html\` string.
-  Use legacy \`nodes\` / \`edges\` only for small previews or truly
-  sequential flows. In architecture/code plans, prefer a repeated section rhythm:
-  recommendation title, confidence and category badges, code-path evidence, a
-  local before/after or current/target spatial diagram, then concise
-  Problem/Solution/Why text.
-- \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
-  only prose usually means the plan is under-specified — include a relevant
-  visual unless the tab is intentionally document-only.
-- \`table\`, \`checklist\`, \`callout\` for scannable structure.
-
-**Open questions live at the bottom as a form when answers would change the
-plan.** Surface answerable unresolved decisions in a final \`question-form\`
-block titled "Open Questions" so the renderer presents it as a distinct section.
-That bottom form is the ONLY place that enumerates the open questions: never add
-a second "Open Questions" heading, list, or recap of the same questions earlier
-in the document. A one-line pointer in the overview prose ("a few decisions are
-still open — see Open Questions below") is fine, but do not reproduce the
-question list or a parallel questions/decisions section above it.
-Use \`single\` or \`multi\` for clear choices, \`freeform\` for constraints,
-\`recommended: true\` for the default you would pick, and option \`wireframe\` /
-\`diagram\` previews only when the options are not already visible in the top
-canvas. \`single\` and \`multi\` questions always render a write-in field so a
-reviewer can answer with a custom option — never add an explicit "Other" option
-yourself; set \`allowOther: false\` only when a free-text answer makes no sense.
-Keep non-answerable assumptions or risks as concise \`callout\` blocks in
-the relevant section. Never bury a questions/decisions wall inside the plan
-narrative, and never ask the same question twice.
-
-For complex plans, do not end without an open-question audit. If architecture,
-scope, UX, data shape, rollout, provider mapping, or ownership still depends on
-a choice, either commit to a recommendation with rationale or add it to the
-bottom form with a recommended default. A complex plan with no open questions is
-fine only when every meaningful decision has been explicitly made.
-
-**Verification must exercise the real workflow.** The final verification section
-should go beyond typecheck/unit tests when the plan changes UI, local files,
-sync, providers, browser behavior, or multi-app flows. Include at least one
-end-to-end smoke that matches the user journey, such as a fresh repo/folder,
-real manifest or data fixture, browser interaction, save/sync action, and an
-on-disk or database assertion. Name the command or manual browser path when it
-is known.
-
-**\`custom-html\` is a bounded escape hatch only** — a single complete fragment
-inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
-placeholder, density demo, or proof that custom HTML works. Prefer the native
-blocks for normal plans. For architecture/code reviews, use \`diagram\`
-\`data.html\` / \`data.css\` for rich local HTML/SVG diagrams instead of
-\`custom-html\`. For UI/product work, \`custom-html\` is never the primary home for a
-requested mockup, UI state, or visual comparison. If UI fidelity requires
-HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
-for that artifact type, not moving the mockup into the document.
-When \`custom-html\` is genuinely needed, author it against the sandbox-provided
-theme tokens (\`--wf-paper\`, \`--wf-card\`, \`--wf-ink\`, \`--wf-muted\`,
-\`--wf-line\`, \`--wf-radius\`, and the matching \`--plan-*\` aliases). Do not hardcode
-hex/rgb/hsl light palettes such as white cards with dark ink; the same fragment
-must read in dark mode without a plan-specific patch.
-
-**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. Check the top canvas in the
-current Plan theme, especially dark mode: white mockup panels, low-contrast
-muted text, or invisible controls are defects. If a frame only works in one
-theme, rewrite the HTML with \`--wf-*\` tokens and semantic helper classes before
-surfacing the plan.
-
-<!-- SHARED-CORE:document-quality END -->`;
-const EXEMPLAR_CORE = `<!-- SHARED-CORE:exemplar START -->
-
-**GOOD.** A UI-first 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, a few \`code\` blocks (grouped in a vertical \`tabs\` block when
-more than one) showing the real shape of the load-bearing files, a \`callout\`
-with \`tone="decision"\` stating the chosen approach with a \`columns\` block
-weighing the two real options behind it,
-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.
-
-**GOOD.** A broad product-architecture plan opens with a plain recommendation
-and one concrete app state before the abstraction. The first canvas artboard is
-pure product UI that matches the current app shell; nearby notes explain the
-user-visible delta. A separate diagram below shows the mechanics, such as file
-or data flow. The document then separates the reusable core from app/provider
-adapters and examples, covers contracts, folder or schema shape, sync
-boundaries, roadmap, non-goals, a bottom Open Questions form for unresolved
-decisions, and a verification section with at least one realistic end-to-end
-smoke. A reviewer who was not in the chat gets the idea from the top snapshot
-before reading the technical plan.
-
-**GOOD.** A \`/visual-plan\` for a backend architecture review: no top canvas.
-The document opens with context and a legend, then repeats recommendation cards:
-title, confidence/category badges, a monospace grid of real file paths, one
-inline two-dimensional before/after or layered architecture diagram, and terse
-Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
-space to show boundaries, layers, and ownership; it is not a default
-left-to-right chain. The plan ends with a top recommendation and a bottom
-question-form only if the next architecture direction is genuinely open. This is
-better than a top canvas because each diagram is local to the claim it supports.
-
-**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
-pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
-frame; a forced desktop + mobile pair for a popover; floating bordered
-annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
-instead of \`html\`; a multi-step UI flow with only static frames and no prototype
-tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
-document with a hero heading and value props that just restates what the canvas
-already shows. Also bad: an architecture-only plan forced into a top canvas of
-labeled boxes with overlapping text, where the actual code evidence and
-recommendations live elsewhere; a product wireframe that mixes a real screen
-with repo names, file-contract arrows, architecture explanations, or a made-up
-permanent inspector; and a plan that describes itself as a revision of a prior
-conversation instead of a standalone proposal. Never produce this.
-
-<!-- SHARED-CORE:exemplar END -->`;
-// Progressive-disclosure reference files. Like `WIREFRAME_REFERENCE_MD`, each of
-// the canvas / document-quality / exemplar cores is the single source of truth
-// for its topic and is materialized verbatim into a sibling `references/*.md`
-// file in the visual-plan skill dir instead of being interpolated inline into
-// the SKILL.md body. The body carries only the matching `*_REFERENCE_POINTER`.
-// Keeping each reference body byte-identical to its core (markers included) lets
-// the sync guard assert the on-disk copies never drift from the constant.
-export const CANVAS_REFERENCE_MD = `# Canvas & artboard placement — single source of truth
-
-This file is the canonical guide for how the visual-plan canvas works: artboard
-placement, lane layout, annotations, patching, and the legacy kit tree. Read it
-in full before authoring or editing any canvas/artboard content; do not author
-canvas layouts from memory or paraphrase these rules per mode.
-
-${CANVAS_SURFACE_CORE}
-`;
-export const DOCUMENT_QUALITY_REFERENCE_MD = `# Plan document quality — single source of truth
-
-This file is the canonical quality bar for the plan document below the canvas:
-how it reads, which blocks to use, how open questions are surfaced, and the
-pre-handoff check. Read it in full before authoring the plan document; it is the
-quality bar. Do not write the document from memory or paraphrase these rules per
-mode.
-
-${DOCUMENT_QUALITY_CORE}
-`;
-export const EXEMPLAR_REFERENCE_MD = `# Good vs. bad exemplar — single source of truth
-
-This file is the canonical worked example of a great plan (and the anti-patterns
-to avoid). Read it alongside the document-quality and canvas references before
-authoring a plan; it is the bar these plans must clear.
-
-${EXEMPLAR_CORE}
-`;
-// Short pointers that replace the inline canvas / document-quality / exemplar
-// cores in the SKILL.md body. Authoring detail lives in the sibling reference
-// files so the SKILL.md stays lean (progressive disclosure); the agent loads the
-// detail on demand.
-const CANVAS_REFERENCE_POINTER = `The canvas is the single source of truth for static UI mockups: the \`surface\`
-locks each artboard's footprint, mixed surfaces lay out
-in lanes, annotations are plain-text designer notes anchored by
-\`targetId\`/\`placement\`, and edits are surgical \`contentPatches\`. Before
-authoring or editing ANY canvas, artboard, or annotation, READ
-\`references/canvas.md\` in this skill directory — it is the single source of truth
-for canvas/artboard mechanics. Do not author canvas layouts from memory.`;
-const DOCUMENT_QUALITY_REFERENCE_POINTER = `The document is a serious technical plan, not marketing: outcome-first,
-prose-first, self-contained, built from the right native blocks, with open
-questions in a single bottom \`question-form\` and a pre-handoff visual check.
-Before authoring the plan document, READ \`references/document-quality.md\` in this
-skill directory — it is the single source of truth for the document quality bar.
-Do not write the document from memory.`;
-const EXEMPLAR_REFERENCE_POINTER = `For a worked example of the bar — a great UI-first plan and \`/visual-plan\`, plus
-the anti-patterns to avoid — READ \`references/exemplar.md\` in this skill
-directory before authoring a plan.`;
-export const CONNECTION_REFERENCE_MD = `# Connecting & publishing — single source of truth
-
-This file is the canonical rule for the never-inline deliverable, finding the
-Plan MCP connector, and restoring it when its tools are missing. It is shared
-word for word by \`/visual-plan\` and \`/visual-recap\`. Read it when you are about
-to publish, or whenever a connector or auth error appears; do not improvise an
-inline fallback from memory.
-
-<!-- SHARED-CORE:connection START -->
-
-**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
-content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
-sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
-entire value is the hosted, interactive, annotatable Plan; an inline summary is
-the thing a Plan replaces, not a degraded version of one. The only supported
-output is to publish through the Plan MCP connector and return its absolute URL.
-Local-files privacy mode (\`references/local-files.md\`) is the one exception.
-
-**The connector is usually the \`plan\` server**, but older installed agents may
-expose the same hosted connector as \`agent-native-plans\` — both names are valid,
-so never report the connector as missing just because it is named
-\`agent-native-plans\` instead of \`plan\`. Some clients also lazy-load connector
-tools through a deferred tool registry instead of showing the namespace upfront.
-Before declaring the connector missing, search/load tools with the host's
-discovery surface (\`tool_search\` when available) for \`create_visual_plan\`,
-\`create_visual_recap\`, or \`get_plan_blocks\`, then use the tools it exposes.
-
-**If the tools are still missing after discovery, do NOT fall back to inline
-output.** The usual cause is a connector that did not finish connecting this
-session (it registers zero tools), NOT necessarily an auth problem — so do not
-assume the user must re-authenticate. Stop and give the user the exact restore
-step for their current client:
-
-- **Codex / Codex Desktop:** run
-  \`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
-  and start a new Codex session.
-- **Claude Code:** run \`/mcp\` and choose Authenticate/Reconnect, or run the same
-  reconnect command with \`--client claude-code\` and restart Claude.
-
-The same applies when a Plan tool returns \`needs auth\`, \`Unauthorized\`, or
-\`Session terminated\`: stop retrying the tool and give the reconnect step instead.
-
-Auth is stored per client config/session, so one client's reconnect does not make
-another running client load tools. \`--client all\` refreshes every local client
-config that already has the Plan entry, but each running client still has to
-reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
-and finds the entry by URL regardless of connector name — never reinstall from
-scratch just to fix auth. Publish once the tool is reachable. Falling back to
-inline content is a defect, not a degraded mode.
-
-<!-- SHARED-CORE:connection END -->
-`;
-export const LOCAL_FILES_REFERENCE_MD = `# Local-files privacy mode — single source of truth
-
-This file is the canonical contract for fully local, no-database planning and
-recaps. It is shared word for word by \`/visual-plan\` and \`/visual-recap\`. Read it
-in full before using local-files mode; do not call any hosted Plan tool for a
-local plan/recap except the schema-only block-catalog lookup described below.
-
-<!-- SHARED-CORE:local-files START -->
-
-**When to use it.** Use local-files privacy mode when the user explicitly asks
-for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
-files, offline/private work, or repo-owned/source-controlled artifacts, or when
-\`AGENT_NATIVE_PLANS_MODE=local-files\` is set. Also use it when a user or repo
-policy says the work must stay under their own brand, domain, source control, or
-infrastructure. In this mode the plan/recap data must never be sent to the Plan
-MCP server or the Plan app action surface. This is the only exception to the
-always-publish rule in \`references/connection.md\`.
-
-The local-files contract:
-
-- **Read context locally.** Read source, diff, and stat context from local files
-  and shell commands only. For recaps, the
-  \`npx @agent-native/core@latest recap collect-diff\`, \`scan\`, and
-  \`build-prompt --local-files\` helpers are safe — they operate on local files and
-  do not write to the Plan database.
-- **Fetch the block catalog first** (it sends no plan content). Use the MCP
-  \`get-plan-blocks\` tool if it is already available, or run
-  \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read that
-  file before authoring MDX; it calls the public no-auth \`get-plan-blocks\` route.
-  Use \`--format schema\` when you need exact nested fields. If network access is
-  unavailable, use the bundled \`references/*.md\` and rely on \`plan local check\` to
-  catch invalid tags. Copy the catalog examples verbatim for the fields the
-  registry table cannot encode: \`checklist\` items need \`id\` and \`label\`;
-  \`question-form\` questions need \`id\`, \`title\`, and \`mode\`, and each option needs
-  \`id\` and \`label\`; and \`Code\` / \`AnnotatedCode\` / \`Diff\` are whitespace-sensitive
-  — encode multiline code as JSON string attributes such as \`code={"const x =\\n  y"}\`
-  (a static template literal is accepted only when it has no \`\${...}\`
-  interpolation). \`plan local check\` is a quick OFFLINE lint (a subset of the
-  renderer schema), so a green \`check\` does not guarantee the plan renders;
-  \`plan local verify\` is the authoritative validation against the real renderer
-  schema.
-- **Write a local MDX folder.** Use \`plans/<slug>/\` to check the artifact into the
-  repo, or a repo-ignored/temporary folder such as \`.agent-native/plans/<slug>/\`
-  or \`/tmp/agent-native-plans/<slug>/\` when it should not be checked in. The
-  folder holds \`plan.mdx\`, optional \`canvas.mdx\`, optional \`prototype.mdx\`, and
-  optional \`.plan-state.json\`. For a recap, set \`kind: "recap"\` and
-  \`localOnly: true\` in the frontmatter/state. Use that exact folder as
-  \`<plan-dir>\` in every command below.
-- **Check, then serve.** Run
-  \`npx @agent-native/core@latest plan local check --dir <plan-dir>\` before any
-  preview, then
-  \`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open\`
-  (use \`--kind plan\` for plans, \`--kind recap\` for recaps). Report the local
-  bridge URL from stdout or \`<plan-dir>/.plan-url\`; treat \`.plan-url\` as a local
-  token file and do not commit it. The URL opens the hosted Plan UI but reads from
-  the localhost bridge on this machine, so it is not shareable across machines. On
-  macOS \`--open\` prefers Chromium browsers; if Safari opens, switch to
-  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
-  HTTP localhost bridge. If the Plan app itself is running locally with the same
-  \`PLAN_LOCAL_DIR\`, the \`/local-plans/<slug>\` route is also valid. In a truly
-  offline environment, hand off the \`<plan-dir>\` path after \`plan local check\` and
-  note that interactive preview requires network access to the hosted Plan UI or a
-  running local Plan app.
-- **Headless verify.** Run
-  \`npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>\`.
-  It starts the bridge, checks the private-network preflight and JSON payload, AND
-  validates the content against the real renderer schema via the Plan app's
-  \`validate-local-plan-source\` action. A non-\`ok\` result with
-  \`validation.valid: false\` lists the renderer's exact schema-path issues (e.g.
-  \`blocks[1].data.tabs[0]...\`); fix those before handing off. If \`validation.ran\`
-  is \`false\`, the Plan app did not expose the validate endpoint (older/unreachable
-  deploy) — point \`--app-url\` at a current Plan app (e.g. a local
-  \`http://localhost:8096\`) for the authoritative check. If the browser hangs on
-  "Loading plan", fetch the \`bridgeUrl\` from the verify/serve JSON to read the
-  concrete validation error.
-- **Never call hosted tools for that plan/recap.** Do not call
-  \`create-visual-plan\`, \`create-ui-plan\`, \`create-prototype-plan\`,
-  \`create-plan-design\`, \`create-visual-recap\`, \`create-visual-questions\`,
-  \`import-visual-plan-source\`, \`update-visual-plan\`, \`patch-visual-plan-source\`,
-  \`get-plan-feedback\`, \`export-visual-plan\`, \`set-resource-visibility\`, or any
-  other hosted Plan tool — except the schema-only block-catalog lookup above.
-- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
-  \`plan local check\`, and rerun \`serve\` or \`verify\` when that preview path is
-  available. Summarize the new local URL when one exists; otherwise summarize the
-  checked \`<plan-dir>\` path. Hosted comments, sharing, screenshots, history, usage
-  attachment, and publish/export receipts are unavailable until the user
-  explicitly opts into publishing.
-
-Local-files mode only prevents plan/recap content from reaching the Agent-Native
-Plan database. It does not by itself make the coding agent's language model local;
-for that stronger boundary the host agent/model must also be local or otherwise
-approved by the user.
-
-<!-- SHARED-CORE:local-files END -->
-`;
-export const VISUAL_PLANS_SKILL_MD = `---
-name: visual-plan
-description: >-
-  Turn ordinary text plans into rich interactive visual plans with diagrams,
-  file maps, annotated code, open questions, and UI/prototype review when
-  useful.
-metadata:
-  visibility: exported
----
-
-# Agent-Native Plans
-
-Agent-Native Plans is structured visual planning mode for coding agents. Build
-the plan you would normally write in Markdown, but as a scannable document with
-editable blocks mixed in: inline diagrams, code snippets,
-open questions, and an optional top visual review area (wireframe canvas, live
-prototype, or both in tabs). Architecture and backend plans stay document-only;
-UI and product plans start with the top canvas/prototype (the Visual Surface
-Choice section owns that rule).
-
-\`/visual-plan\` is the packaged command and main entry point. Choose the review
-mode from the task: UI-first when the work is primarily product UI and review
-should start with screens, prototype-first when review should start with a
-functional live prototype, design-first when review needs full-fidelity branded
-screens, or visual-intake when the user explicitly wants a questionnaire before
-planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,
-\`/visual-plan\` uses that source plan as the starting point and builds the review
-surface from it instead of starting over.
-
-## When To Use
-
-Create or adapt a visual plan whenever the plan would be better as a reviewable
-artifact than a chat paragraph. This includes modest work such as a single UI
-surface with states, a small workflow, a before/after product change, or a
-component/API/data-shape decision that needs alignment, plus larger multi-file,
-ambiguous, long-running, risky, or UI-heavy work. Use it when architecture /
-data flow / UI direction / options / open questions would benefit from inline
-diagrams or structured blocks, when the user needs to react to a direction
-before you implement, or when an existing text plan needs a richer review
-surface.
-
-## Plan Discipline
-
-- **Gate thoughtfully.** A visual plan is a richer review surface, not only a
-  tool for giant projects. Use it when the user needs to see, compare, comment
-  on, or approve a direction before code, even for a modest UI/state/workflow
-  change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a
-  single well-specified function, anything whose diff you could describe in one
-  sentence — and just make the change. Never pad a plan with filler and never
-  ship a single-step plan.
-- **Research before you draft.** Read the real files, actions, schema, and
-  patterns first; name actual files, symbols, and data shapes instead of
-  inventing them. Check existing \`actions/\` before proposing endpoints and prefer
-  named client helpers over raw fetch. Delegate wide exploration to a sub-agent.
-  Lead with reuse: for each step, name what it reuses — existing actions, schema,
-  components, helpers — before what it adds, so the plan explains the genuinely new
-  delta instead of redescribing what already exists.
-- **Decide the hard-to-reverse bets first.** For non-trivial backend, data, or API
-  work, sketch where the feature is headed, then call out the decisions that are
-  expensive to undo once data or callers depend on them — wire format, public ids,
-  data-model shape, auth and ownership boundaries — and get those right in the plan
-  even if most of the feature ships later. Then scope to the smallest first cut that
-  proves the approach without foreclosing it, stating both what is in and what is
-  explicitly deferred.
-- **Keep examples at the right altitude.** When the user's idea is a broad
-  framework, product, or operating-model change, do not collapse it into the
-  first concrete example, provider, or sync path they mention. Separate the core
-  abstraction from motivating examples and app/provider adapters. Use examples
-  to make the plan legible, but label them as examples unless they are the whole
-  requested scope.
-- **Publish standalone plans.** If the user pasted, referenced, or already has a
-  Codex / Claude Code / Markdown plan, treat it as source material, but rewrite
-  the published plan as a clean standalone proposal. Preserve the source plan's
-  useful intent and codebase facts, label inferred visuals as inferred, and avoid
-  revision language such as "preserve the prior plan", "do not drop the old
-  idea", "unlike the previous version", or "this revision changes...". A reader
-  who never saw the chat or earlier drafts should understand the plan.
-- **Make the first read concrete.** If the plan is meant to be shared with
-  someone outside the chat, or if the concept is abstract, lead near the top with
-  one concrete product example before mode tables, architecture, or roadmaps. For
-  UI-capable concepts, that usually means a top-canvas app state that shows the
-  real user workflow in product terms. Do not rely on phrases that only make
-  sense in conversation, and do not frame the plan as "not the old idea"; state
-  the positive model directly.
-- **Planning is read-only.** Make no source edits while building or reviewing the
-  plan. Start editing only after the user approves the direction.
-- **Clarify vs. assume.** Do not ask how to build it — explore and present the
-  approach and options in the plan. Ask a clarifying question only when an
-  ambiguity would change the design and you cannot resolve it from the code; use
-  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
-  questions before finalizing. Do not call \`create-visual-questions\` for
-  ordinary clarification or preflight; reserve it for the visual-intake mode when
-  the user explicitly asks for a visual intake questionnaire. Otherwise state the
-  assumption explicitly and proceed, and keep anything unresolved in the plan's
-  single bottom \`question-form\` Open Questions block. For complex plans, do a
-  final open-question pass before handoff: if a decision would affect
-  architecture, scope, UX, data shape, or rollout, either decide it in the plan
-  with rationale or put it in that bottom form with a recommended default.
-- **The plan is the approval gate.** After surfacing it, ask the user to review
-  and approve before you write code, and name which files/areas the work touches.
-  Presenting the plan and requesting sign-off is the approval step — do not ask a
-  separate "does this look good?" question.
-- **The document is the source of truth, not the chat.** When scope shifts,
-  update the plan with \`update-visual-plan\` rather than only changing course in
-  chat, and make the updated document stand alone. Do not describe the update as
-  a correction to an earlier draft inside the plan itself. Re-read the approved
-  plan before major steps.
-
-## Create A Structured Agent-Native Plan — Never Inline
-
-The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.
-The hosted Plan MCP connector (\`plan\` server, or legacy \`agent-native-plans\`) is
-the default collaboration and commenting surface; it is not a reason to reject
-the planning pattern as an external dependency or rented layer. Plans are
-portable source artifacts (\`plan.mdx\`, optional \`canvas.mdx\` /
-\`prototype.mdx\`, JSON, and HTML export), and ownership-sensitive workflows can
-use local-files mode or a self-hosted/custom Plan app URL without abandoning the
-skill's review discipline. Do not advise the user to skip \`/visual-plan\` because
-the default surface is hosted; choose the right Plan mode for the user's
-ownership, privacy, sharing, and branding needs.
-
-By default, create the plan via the Plan MCP connector and NEVER hand it over as
-inline chat content — no Markdown prose, ASCII sketch, table, or fenced
-wireframe. If the \`plan\` (or legacy \`agent-native-plans\`) tools are not visible,
-discover them through the host's \`tool_search\` first; if they are still missing,
-STOP and give the user the client-specific reconnect step rather than improvising
-an inline plan. Before publishing, or whenever a connector or auth error appears,
-READ \`references/connection.md\` in this skill directory — it is the single source
-of truth for the never-inline rule, connector discovery, and the per-client
-reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.
-
-## Core Workflow
-
-This section describes the default hosted Plan MCP workflow. If
-\`AGENT_NATIVE_PLANS_MODE=local-files\` is set, or the user asks for fully local
-files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
-forward only the code-research and plan-composition guidance here.
-
-1. Follow the host agent's normal planning flow: inspect the codebase, delegate
-   wide exploration when useful, gather the info needed, and ask native
-   clarifying questions as needed before generating the plan. If a source plan
-   already exists, gather its exact text from the user's paste, a referenced
-   file, or recent visible agent context; do not invent source text.
-2. Call \`get-plan-blocks\` for the authoritative block catalog — do not author
-   from memorized tags. Then call the mode-matched create tool:
-   \`create-visual-plan\` for document-first plans (architecture, backend, data,
-   refactor, API), \`create-ui-plan\` for UI-first plans, \`create-prototype-plan\`
-   for prototype-first plans, \`create-plan-design\` for design-first plans,
-   \`create-visual-questions\` only when the user explicitly asks for a visual
-   intake questionnaire. When a source plan already exists,
-   pass it as \`planText\` and preserve the original plan's useful intent while
-   producing a standalone plan document, not a revision memo.
-3. For UI/product plans, compose the top canvas first with the primary
-   wireframes and annotated states, then write the document with native blocks
-   (see \`references/canvas.md\` and \`references/document-quality.md\`). For
-   broad product architecture plans with a user-facing implication, add a
-   concrete "what this looks like in the app" visual before the abstract
-   architecture or mode tables. Keep the document close to the standalone
-   Markdown plan the agent would normally output. If an existing plan was
-   provided, carry forward the right facts and decisions without referring to
-   the previous draft or explaining how this version differs. For non-visual
-   plans, skip the top visual surface (Visual Surface Choice below owns the rule)
-   and put \`diagram\`, \`data-model\`,
-   \`api-endpoint\`, \`diff\`, \`file-tree\`, \`code\`, and \`annotated-code\` blocks
-   directly next to the relevant prose.
-   Wide document layout is renderer-owned and intentionally allowlisted: only
-   literal code-review surfaces (\`diff\`, \`annotated-code\`) and \`tabs\` blocks
-   with vertical orientation or diff-like children break out wider than prose.
-   Keep \`api-endpoint\`, \`openapi-spec\`, \`data-model\`, \`json-explorer\`,
-   \`wireframe\`, question, and \`custom-html\` blocks in normal document flow unless
-   their own renderer says otherwise.
-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 — a convenience and smoke test, never the
-   only handoff or the access
-   model. Plans should load out of the box for the local agent and local browser
-   session; if a signed-in embedded browser cannot read a local plan that an
-   anonymous/tool check can read, fix the app/action ownership or access path
-   rather than patching one plan by hand. For high-stakes plans (architecture,
-   backend, data, multi-file, or risky), also kick off the self-review pass in
-   **Self-Review Before Handoff** while the user reads, instead of blocking the
-   handoff on it.
-5. For hosted plans, 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. For hosted plans, apply changes with \`update-visual-plan\`, preferring
-   targeted \`contentPatches\`.
-   Treat the top-level \`content\` payload as a full replacement, not a merge; do
-   not send a partial \`content\` object to add a canvas or one block. If a full
-   replacement is unavoidable, first read the complete plan source/content, carry
-   forward every existing block and visual surface, and verify the source/export
-   afterward so the document body was not truncated. When the user wants
-   source-control friendly edits, use \`patch-visual-plan-source\` against the MDX
-   files instead of regenerating the plan.
-7. For hosted plans, export with \`export-visual-plan\` only when the user wants a
-   shareable receipt or repo-check-in artifacts.
-
-## Self-Review Before Handoff
-
-For high-stakes plans — architecture, backend, data-model, migration, multi-file,
-or otherwise risky work — run one adversarial self-review pass before treating the
-plan as final. Skip it for small, UI-only, or single-decision plans where the cost
-outweighs the value. Keep the pass cheap and non-blocking:
-
-- **Surface the plan first, review concurrently.** Post the link and let the user
-  start reading, then run the review in parallel — never make the user wait on it.
-- **Review the written plan; do not re-research.** Critique the plan text and its
-  own blocks. The grounding was already done while drafting, so the review checks
-  the output instead of re-exploring the repo.
-- **Spawn one skeptical reviewer** whose only job is to find what is weak, missing,
-  or wrong — not to praise. Point it at: hard-to-reverse decisions made implicitly
-  or not at all (wire format, public ids, data-model shape, auth, ownership); steps
-  not anchored in real files or symbols; a menu of options where the plan should
-  commit to one; obvious missing decisions ("what happens when X?", "why not Y?");
-  and padding or single-step filler.
-- **Fix vs. ask.** Apply clear-cut fixes yourself with \`update-visual-plan\`
-  \`contentPatches\` — vague non-goals, unanchored claims, an obvious missing
-  decision. Route genuine judgment calls back to the user instead: add them to the
-  bottom \`question-form\` Open Questions block or batch them into the normal
-  ask-user-question flow. Do not silently decide them.
-- **Do not surprise the user mid-read.** On a large plan, apply the patches before
-  the editor loads; otherwise note briefly that a self-review is running so the
-  plan changing under them is expected. When you next respond, summarize what the
-  review changed and what it surfaced for the user to decide.
-
-## Visual Surface Choice
-
-Choose the surface before creating the plan or after reading the source plan. Do
-not add visual chrome by default:
-
-For UI/product plans, the top canvas is usually the primary review surface. Put
-the first meaningful wireframes there, not buried as document-body blocks. Use
-multiple canvas artboards when states matter, such as the default view, an
-overflow menu or popover, a side panel, loading, or error. Put short annotations
-beside frames with \`targetId\` plus \`placement\`; keep implementation details,
-tradeoffs, file maps, data contracts, risks, and verification in the document
-body below the canvas.
-
-When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what
-this looks like", treat that as a canvas-first request. Make one artboard per
-user-visible state, connect only adjacent transitions, and use short canvas
-annotations for the product notes. Do not substitute a document-body \`diagram\`
-block for the requested storyboard just because HTML diagrams are faster to
-write; diagrams belong below the canvas for backend mechanics, architecture, or
-data-flow explanation.
-
-Keep product wireframes and explanatory/meta diagrams separate. Start with pure
-screens that look like the app state under discussion, without callout prose or
-architecture notes embedded inside the UI. Put arrows, labels, contracts, data
-flow, and mode explanations in separate annotations, separate canvas diagrams,
-or the document body.
-
-When the plan touches an existing app, inspect the current shell/components
-before drawing. The first artboard should look like the real app at the same
-density: existing sidebars, toolbar placement, overflow menus, app chrome, and
-framework agent chrome stay in their real places. Model secondary surfaces as
-separate states, such as a top-right overflow popover, sheet, panel, loading
-state, or separate AgentSidebar, rather than inventing a permanent inspector or
-folding framework chrome into the product UI.
-
-- **No visual surface** for architecture-only, backend-only, data migration,
-  copy-only, or otherwise non-visual plans. Do not use the top canvas for
-  architecture diagrams, dependency maps, file plans, API contracts, or
-  data-flow-only reviews. Use a strong document with local inline diagrams
-  only when relationships need a visual explanation, usually one spatial diagram
-  per recommendation or decision. Prefer grouped regions, layers, quadrants,
-  matrices, or before/after panels over a single-axis chain unless the
-  relationship is truly sequential.
-- **Canvas only** for one static screen, a before/after comparison, a component
-  state, a small popover, or a visual direction that does not require clicking.
-  Put those wireframes in \`content.canvas\` and omit \`content.prototype\`.
-- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
-  review/approval flows, navigation changes, or anything where the reviewer
-  needs to operate the behavior. Keep the static wireframes in
-  \`content.canvas\`, add the aligned functional prototype in
-  \`content.prototype\`, and rely on the top visual tabs to switch between them.
-- **Prototype-first** when the user asks to operate the UI or when interaction is
-  the main question. Use \`create-prototype-plan\`, which still preserves static
-  mocks where useful.
-
-For mixed canvas + prototype plans, reuse the same real labels, app statuses,
-and screen ids across both surfaces. The canvas is the inspectable static reference;
-the prototype is the interactive version of that same flow, not a separate
-design direction.
-
-## Wireframe quality — read \`references/wireframe.md\`
-
-UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
-pinned bottom bars, real product content, before/after comparability, the right
-\`surface\` preset, \`--wf-*\` tokens instead of hex, and no \`<html>\`/\`<style>\`/font
-tags. Before authoring ANY wireframe / \`<Screen>\` / \`WireframeBlock\`, READ
-\`references/wireframe.md\` in this skill directory — it is the single source of
-truth for HTML wireframe quality, shared word for word with \`/visual-plan\`
-and \`/visual-recap\`. Do not author wireframes from memory.
-
-## Canvas — read \`references/canvas.md\`
-
-The canvas is the single source of truth for static UI mockups: the \`surface\`
-locks each artboard's footprint, mixed surfaces lay out
-in lanes, annotations are plain-text designer notes anchored by
-\`targetId\`/\`placement\`, and edits are surgical \`contentPatches\`. Before
-authoring or editing ANY canvas, artboard, or annotation, READ
-\`references/canvas.md\` in this skill directory — it is the single source of truth
-for canvas/artboard mechanics. Do not author canvas layouts from memory.
-Canvas artboards use the same HTML wireframe path as document-body
-\`WireframeBlock\` screens: author \`<Screen surface="..." html={...} />\` with a
-semantic HTML fragment. Do not author fresh kit-tree children such as
-\`<FrameScreen>\`, \`<Card>\`, \`<Row>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags;
-those are legacy compatibility markup for old plans and produce brittle canvas
-layouts.
-
-## Document quality — read \`references/document-quality.md\`
-
-The document is a serious technical plan, not marketing: outcome-first,
-prose-first, self-contained, built from the right native blocks, with open
-questions in a single bottom \`question-form\` and a pre-handoff visual check.
-Before authoring the plan document, READ \`references/document-quality.md\` in this
-skill directory — it is the single source of truth for the document quality bar.
-Do not write the document from memory.
-
-## Good vs. bad exemplar — read \`references/exemplar.md\`
-
-For a worked example of the bar — a great UI-first plan and \`/visual-plan\`, plus
-the anti-patterns to avoid — READ \`references/exemplar.md\` in this skill
-directory before authoring a plan.
-
-## Tool Guidance
-
-- \`create-visual-plan\`: start one structured visual plan per agent task/run, or
-  import an existing text plan by passing \`planText\`; \`content\` may include no
-  visual surface, canvas only, or canvas + prototype.
-- \`create-ui-plan\`: start a UI-first plan when the work is primarily product UI.
-- \`create-prototype-plan\`: start a prototype-first plan with a functional top
-  review surface.
-- \`create-plan-design\`: start a full-fidelity branded Design-tab plan with an
-  optional matching Prototype tab.
-- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
-  into a prototype plan.
-- \`create-visual-questions\`: use only when the user explicitly asks for a visual
-  intake questionnaire, not as \`/visual-plan\` preflight.
-- \`update-visual-plan\`: revise content, status, or comments with targeted
-  \`contentPatches\` (see Core Workflow step 6).
-- \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
-  optional \`canvas.mdx\`, optional \`.plan-state.json\`, and JSON.
-- \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
-  artboard, annotation, component, or wireframe-node id.
-- \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
-- \`get-visual-plan\`: read the current structured plan, exported HTML, and
-  annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently; it
-  returns grouped threads, exact anchor details, expected resolver, and recent
-  review-event payloads so agents can act only on the comments meant for them.
-- \`get-plan-blocks\`: resolve block tags before authoring — do not memorize tags;
-  call this first to get the authoritative tag names, required fields, and prop
-  shapes from the live block registry.
-- \`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.
-
-## Local-Files Privacy Mode — read \`references/local-files.md\`
-
-When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
-publish, fully local/offline/private planning, repo-owned source-controlled
-artifacts, or \`AGENT_NATIVE_PLANS_MODE=local-files\` — do not call any hosted Plan
-tool except the schema-only \`get-plan-blocks\` catalog lookup. Author a local MDX
-folder and
-preview it with \`plan local check\` / \`plan local serve\` / \`plan local verify\`.
-Before using local-files mode, READ \`references/local-files.md\` in this skill
-directory — it is the single source of truth for the full contract (catalog
-lookup, MDX folder layout, the local bridge commands, and the hosted tools you
-must not call). Carry forward only the code-research and plan-composition
-guidance from Core Workflow; everything hosted is replaced by the local bridge.
-
-## Interpreting comment anchors
-
-This section applies to hosted plans with \`get-plan-feedback\` /
-\`update-visual-plan\`. In local-files mode, do not call hosted feedback or update
-tools; interpret file/chat feedback directly, edit the MDX files, rerun the
-local bridge check/serve/verify command, and report the new local URL.
-
-\`get-plan-feedback\` returns rich anchors — read them before acting on any comment.
-
-- **Coordinate frames.** \`targetX\`/\`targetY\` are percentages *within* the
-  element named by \`targetSelector\`/\`targetKind\`. Bare \`x\`/\`y\` are percentages
-  of the whole plan document. \`canvasX\`/\`canvasY\` are raw board-world pixels on
-  the design canvas (board size given when available).
-- **Wireframe pins.** Anchors on wireframes include \`targetNodeId\` and
-  \`targetNodePath\` (e.g. \`card > list > listItem "Acme Inc"\`) identifying the
-  exact kit node. Use \`targetNodeId\` directly with wireframe node patch ops;
-  use \`data-design-id\` values from design artboards with
-  \`update-design-element-style\`. Prefer the node id/path over raw coordinates;
-  fall back to coordinates plus the focused screenshot (red ring marks the exact
-  point) only when no node id is present.
-- **Text quotes.** Resolve \`textQuote\` against current prose using
-  \`contextBefore\`/\`contextAfter\` for disambiguation. If \`ambiguous: true\`, ask
-  the user — do not guess which occurrence is meant.
-- **Detached comments.** \`get-plan-feedback\` flags threads whose quoted text no
-  longer exists as \`detached\` (in \`detachedThreads\`). Reconcile these against
-  rewritten content — never silently drop them.
-- **Routing.** \`resolutionTarget\` is the only routing signal: act on \`agent\`,
-  treat \`human\` as context only. \`@mentions\` are people to notify, never a
-  routing signal.
-- **Two-axis state.** Mark every ingested comment as consumed
-  (\`consumedCommentIds\` on \`update-visual-plan\`). Set \`status=resolved\` only on
-  agent-targeted comments you actually addressed; leave human-targeted comments
-  open.
-
-## Visibility & Sharing
-
-Use \`set-resource-visibility\` to change who can see a plan (e.g. public, login,
-or org-scoped). Use \`share-resource\` to grant specific users or roles access
-by email or role. Gate visibility before sharing any plan that covers
-unreleased or private work — default to the narrowest scope that meets the
-review need.
-
-## 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 runs
-auth/setup for the selected local client(s) in the same step (a one-time browser
-sign-in at setup — this is intended), so the first tool call in that client does
-not hit an OAuth wall:
-
-\`\`\`bash
-npx @agent-native/core@latest skills add visual-plans
-\`\`\`
-
-After that, \`/visual-plan\`, \`/visual-recap\`, and \`/visualize-repo\` are the
-installed slash commands. If you only need one command, use
-\`skills add visual-plan\`, \`skills add visual-recap\`, or
-\`skills add visualize-repo\` instead. The other planning modes
-(\`create-ui-plan\`, \`create-prototype-plan\`, \`create-plan-design\`,
-\`create-visual-questions\`) are MCP tools reachable from \`/visual-plan\`, not
-separate slash commands. Pass \`--no-connect\` to register the connector without
-authenticating, then run
-\`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
-whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
-loading are per client config/session.
-
-**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.
-
-For repo-wide visual docs, run
-\`npx @agent-native/core@latest visualize-repo --open\` to create/update
-\`agent-native.json\`, seed \`.agent-native/visual-docs/repo-overview\`, and open
-the local bridge.
-
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`, do
-not keep retrying it — stop and give the user the per-client reconnect step from
-\`references/connection.md\`, 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_RECAP_SKILL_MD = `---
-name: visual-recap
-description: >-
-  Turn a PR, branch, commit, or git diff into an interactive visual recap with
-  diagrams, file maps, API/schema summaries, annotated diffs, and focused review
-  notes.
-metadata:
-  visibility: exported
----
-
-# Visual Recap
-
-\`/visual-recap\` creates a visual plan built **from** a diff, not toward one. It
-is the reverse of forward planning: instead of describing the change you are
-about to make, you describe the change that was just made, at a higher altitude
-than line-by-line review. The same plan data model serves both directions —
-schema, API, file, and architecture changes become the same \`data-model\`,
-\`api-endpoint\`, \`file-tree\`, and \`diagram\` blocks a forward plan would use, only
-now they summarize work that exists. A reviewer scans the shape of the change
-before spending attention on the literal lines.
-
-## Publish As An Agent-Native Plan — Never Inline
-
-The deliverable is ALWAYS a published Agent-Native Plan, created with
-\`create-visual-recap\` on the Plan MCP connector — NEVER inline chat content (not
-Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the
-recap" summary). A recap's entire value is the hosted, interactive, annotatable
-plan; an inline summary is not a degraded recap, it is the thing a recap
-replaces. If the \`plan\` (or legacy \`agent-native-plans\`) tools are not visible,
-discover them through the host's \`tool_search\` first; if they are still missing,
-STOP and give the user the client-specific reconnect step rather than improvising
-an inline recap. Before publishing, or whenever a connector or auth error
-appears, READ \`references/connection.md\` in this skill directory — it is the
-single source of truth for the never-inline rule, connector discovery, and the
-per-client reconnect steps. Local-files privacy mode (below) is the one
-exception.
-
-## Local-Files Privacy Mode — read \`references/local-files.md\`
-
-When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
-publish, fully local/offline/private recaps, or \`AGENT_NATIVE_PLANS_MODE=local-files\`
-— do not call any hosted Plan tool except the schema-only \`get-plan-blocks\`
-catalog lookup. Read the diff with the local \`recap collect-diff\` / \`scan\` /
-\`build-prompt --local-files\` helpers, author a local MDX folder (set
-\`kind: "recap"\` and \`localOnly: true\`), and preview it with \`plan local check\`,
-\`plan local serve --kind recap\`, and \`plan local verify --kind recap\`. Before
-using local-files mode, READ \`references/local-files.md\` in this skill directory
-— it is the single source of truth for the full contract.
-
-## When To Use
-
-Build a recap when a PR or commit is large, multi-file, or touches schema, API
-contracts, or architecture, and a reviewer would benefit from seeing the change
-mapped to structured blocks before reading the raw diff. A GitHub Action can
-generate one automatically from a PR diff; an agent can generate one on request
-("recap this PR", "show me what this branch changed"). Skip it for small,
-single-file, or obvious diffs — a recap is review overhead, and a tiny change
-reviews faster as plain diff.
-
-## Recap The Whole Work Unit
-
-When \`/visual-recap\` is invoked in a chat thread after work has already happened,
-the default scope is the whole current work unit/thread, not only the most recent
-user message, tool action, or follow-up fix. Gather the thread-owned changes
-across the conversation: original implementation work, later bug fixes, UI
-follow-ups, tests, changesets, skill/instruction updates, generated plan/source
-artifacts, and any local import/linking fixes needed to make the recap open.
-
-Use the current diff plus conversation context to separate thread-owned changes
-from unrelated dirty work that existed before the thread. Exclude unrelated
-pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred,
-state the assumption or ask a concise question before publishing.
-
-When updating an existing recap after feedback, revise the recap so it still
-covers the whole thread/work unit plus the new correction. Do not replace a broad
-recap with a narrow recap of only the latest feedback unless the user explicitly
-asks for that narrower scope.
-
-## Keep The Recap Body Lean
-
-Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to
-the generated plan body. In particular, do not create a \`rich-text\` block just to
-say the recap is an aid, that the reviewer should still review the diff, how many
-files changed, or which ref/working tree generated the recap. The plan title,
-brief, and \`file-tree\` (which carries the per-file change stats) already carry
-that context.
-
-Only add prose blocks when they tell the reviewer something specific about the
-change that the structured blocks do not: the objective, a real compatibility
-risk, an important decision visible in the diff, or a grounded review note.
-
-## Recaps Must Be Substantial
-
-Lean is not the same as thin. A recap is not a single wireframe plus one
-sentence — that under-serves the reviewer as much as boilerplate prose over-serves
-them. Alongside the visual/structural headline (wireframes, \`data-model\`,
-\`api-endpoint\`, \`diagram\`), a substantial recap also carries the implementation
-evidence:
-
-- A short surface/state inventory before authoring: list the changed routes,
-  components, popovers/dialogs, role/access states, empty/error states, and
-  shared abstractions visible in the diff. The final recap must either represent
-  each meaningful item with a block or intentionally omit it because it is tiny,
-  redundant, or not user-visible.
-- A \`file-tree\` of the changed files with each entry's \`change\` flag, so the
-  reviewer sees the footprint of the work at a glance.
-- The split \`diff\` of the KEY changed files, grouped under a \`## Key changes\`
-  \`rich-text\` heading in a single horizontal \`tabs\` block (the default
-  orientation, one file per tab), with a one-line \`summary\` and a few
-  \`annotations\` on each — so the reviewer can drop from the high-altitude shape
-  straight into the load-bearing code. Use horizontal file tabs, not a vertical
-  side rail, so the selected file has enough width for the side-by-side diff.
-
-Skip the diff appendix only for a genuinely tiny change that reviews faster as
-plain diff (see "When To Use"); for any change worth recapping, the file-tree and
-key-change diffs belong in the plan.
-
-## Canonical Shape And Budgets
-
-A strong recap follows one skeleton, top to bottom:
-
-1. UI-impact headline — wireframes first, when the diff changed rendered UI.
-2. Short outcome narrative (\`rich-text\`): what changed and why, 1-3 paragraphs.
-3. \`data-model\` / \`api-endpoint\` blocks for schema and contract changes.
-4. \`file-tree\` of the changed files with \`change\` flags.
-5. \`## Key changes\` — one horizontal \`tabs\` block of \`diff\` / \`annotated-code\`.
-
-Budgets that keep the recap reviewable:
-
-- 3-8 key-change tabs. Fewer than 3 on a large change under-serves the
-  reviewer; more than 8 stops being a summary.
-- Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per
-  tab; summarize or link the rest of a long file instead of dumping it.
-- Title at most ~70 characters; brief 1-3 sentences.
-
-**GOOD.** A 25-file auth change: Before/After wireframes of the login surface,
-a two-paragraph narrative, a diff-aware \`data-model\` of the sessions table, an
-\`api-endpoint\` for the new refresh route, a \`file-tree\` with change flags, and
-\`## Key changes\` with five focused tabs, each with a one-line \`summary\` and a
-few annotations on the load-bearing hunks.
-
-**BAD.** One giant unsegmented diff dump with no summaries or annotations; or a
-sparse three-block recap of a 40-file change (one wireframe, one sentence, one
-file list) that forces the reviewer back into the raw diff anyway.
-
-## UI Impact Needs Wireframes
-
-When the diff changes rendered UI, layout, density, visual state, interaction
-affordances, navigation, controls, menus, dialogs, or design tokens, the recap
-MUST include one or more wireframes. Prose and file diffs are not a substitute
-for showing what changed visually.
-
-Before choosing wireframes, make a UI coverage pass from the diff:
-
-- Identify the entry surface where the change appears, such as a page header,
-  list row, toolbar, route shell, or menu trigger.
-- Identify the interaction surface that opens or changes, such as a popover,
-  dialog, tab, sheet, dropdown, inline editor, or toast.
-- Identify the resulting destination or persistent state, such as a public page,
-  read-only view, empty state, error state, loading state, permission-denied
-  state, or saved/shared state.
-- Identify access or role variants when permissions change. Owner/admin/editor
-  versus viewer/non-manager differences are visual behavior and need a compact
-  matrix, paired wireframes, or clearly labeled state sequence.
-
-For UI-heavy PRs, a single before/after of the entry surface is not enough.
-Show the changed entry point, the main changed interaction surface, and the
-resulting/destination state. Add more states when the diff adds tabs, role-based
-controls, public/private visibility, invite/manage flows, destructive controls,
-or empty/error branches.
-
-Choose the smallest visual surface that makes the review clear:
-
-- Use a \`Before\` / \`After\` wireframe pair when the reviewer benefits from direct
-  comparison, such as a removed or added control, a changed state, layout
-  density, ordering, navigation, or a visible component replacement.
-  \`references/wireframe.md\` owns how to lay that pair out (columns vs.
-  vertical stack by geometry).
-- Use an after-only wireframe when the change is purely additive or the "before"
-  state would only show absence without adding review value.
-- Use more than two wireframes when the UI change is flow-dependent, responsive,
-  or stateful; show the meaningful states in order instead of forcing a single
-  before/after pair.
-- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
-  matching \`surface\` (\`popover\`, \`panel\`, etc.) and show the focused sub-surface.
-  Do not redraw a full page unless placement in the page is itself part of the
-  change.
-
-Ground each wireframe in the changed UI behavior, component names, file paths,
-and diff-visible labels/states. If exact pixels are inferred rather than
-captured, say so in the wireframe caption or a concise annotation. For
-local/manual recaps, import or update the plan source that holds the wireframes
-so the rendered recap opens with the UI visual available.
-
-## Wireframe Quality — read \`references/wireframe.md\`
-
-UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
-pinned bottom bars, real product content, before/after comparability, the right
-\`surface\` preset, \`--wf-*\` tokens instead of hex, and no \`<html>\`/\`<style>\`/font
-tags. Before authoring ANY wireframe / \`<Screen>\` / \`WireframeBlock\`, READ
-\`references/wireframe.md\` in this skill directory — it is the single source of
-truth for HTML wireframe quality, shared word for word with \`/visual-plan\`
-and \`/visual-recap\`. Do not author wireframes from memory.
-
-Use the standard \`WireframeBlock\` / \`<Screen>\` format so the Plan viewer owns the
-surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate
-when placement precision matters, especially popovers, menus, dialogs, and dense
-forms. For HTML
-wireframes, keep \`renderMode\` unset or \`wireframe\` unless a design-only editable
-mockup is explicitly required, because \`renderMode="design"\` disables the
-sketchy rough overlay.
-
-When a browser tool is available, render a UI-impact recap in the Plan viewer
-and visually inspect it at the current theme before sharing. If any label,
-annotation, toolbar, or wireframe content overlaps another element, fix the MDX
-and re-import before reporting the link. A text-match screenshot is not enough;
-visually inspect the captured image. When no browser is available (for example
-a headless CI agent), state that in the recap handoff instead.
-
-## Top Canvas Recaps — read \`../visual-plan/references/canvas.md\`
-
-When a recap includes a top canvas, storyboard, or flow view, READ
-\`../visual-plan/references/canvas.md\` before authoring \`canvas.mdx\`. Recap
-canvas artboards must use the same HTML wireframe path as good document-body
-wireframes: \`<Screen surface="..." html={...} />\` with a semantic HTML fragment.
-Do not author fresh kit-tree children such as \`<FrameScreen>\`, \`<Card>\`,
-\`<Row>\`, \`<Title>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags. Those components
-are legacy compatibility markup for old plans; in new canvas storyboards they
-can produce cramped or overlapping layouts even when the inline body wireframe
-looks good. If a canvas mockup looks worse than the same screen below the fold,
-assume it used the legacy kit path and replace it with an HTML screen.
-
-## Open And Report The Recap
-
-In local-files privacy mode, run \`plan local check\` first, then report the local
-bridge URL from
-\`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open\`
-or from \`<plan-dir>/.plan-url\`. It opens the hosted Plan UI but reads from the
-localhost bridge on this machine, so it is not shareable across machines. If the
-Plan app itself is running locally with the same \`PLAN_LOCAL_DIR\`, the
-\`/local-plans/<slug>\` route is also valid. Do not invent a hosted database URL
-and do not publish just to get an absolute Plan link.
-
-After creating the recap, link the reviewer to the rendered plan with an
-**absolute URL on the origin whose database actually holds the plan**. That
-origin is the Plan MCP server you just created the recap through — NOT whatever
-dev server you happen to know is running. The create tool returns the correct
-link; report THAT. Never make the primary link a local \`plan.mdx\` file, a local
-mirror folder, or a relative path such as \`/plans/<id>\`.
-
-When the recap is posted to a PR for a private repo, the plan link is not a
-public URL. Make the PR comment/handoff copy explicit: reviewers may need to
-sign in to Agent-Native Plans with an account that has access to the owning
-organization before the link loads. Use wording like: "Private repo recap:
-sign in with access to this org if the plan does not open." Do not imply the
-link is broken or public when access is gated by repo/org visibility.
-
-A recap lives only in the database of the MCP that created it. A separately
-running local dev server (e.g. \`http://localhost:8081\`) has its OWN database and
-will NOT contain a recap created through the hosted MCP, so a hand-built
-\`localhost\` link returns "Plan not found". This is the most common recap
-mistake — do not guess an origin you have not confirmed shares the MCP's data.
-
-Resolve the URL in this order:
-
-1. Use the absolute URL the create tool RETURNS — \`openLink.webUrl\`, else the
-   \`visualUrl\` in the returned \`plan.mdx\` frontmatter, else \`url\`/\`path\`
-   resolved against the MCP server's own origin (for the hosted MCP that is
-   \`https://plan.agent-native.com\`). This always points at the database that has
-   the plan.
-2. Use a \`localhost\`/dev origin ONLY when the recap was created through a Plan
-   MCP bound to that same origin — i.e. that MCP's url is
-   \`http://localhost:<port>/_agent-native/mcp\`. Creating through the hosted MCP
-   and linking to localhost is the exact mismatch that 404s.
-3. If only a plan id is available, build the MCP origin's absolute URL
-   (hosted: \`https://plan.agent-native.com/plans/<id>\`) and say it was inferred.
-
-If the user wants to review on localhost but the recap was created through the
-hosted MCP, say so plainly: the local dev server cannot see it. To view a recap
-on localhost (e.g. to exercise un-deployed local renderer changes), they must
-connect a LOCAL Plan MCP (\`http://localhost:<port>/_agent-native/mcp\`) and
-re-create the recap through it so it lands in the local database; offer to do
-that rather than handing over a localhost URL that will not resolve.
-
-When running in Codex and the Browser/in-app side browser tools are available,
-open the returned absolute recap URL there automatically after creation. Still
-include the same absolute URL in the final response. Local mirror files like
-\`plans/<slug>/plan.mdx\` may be mentioned only as secondary source-control
-artifacts, not as the main way to open the recap.
-
-## Diff → Block Mapping
-
-Map each kind of change to the block that carries it, derived mechanically from
-the actual diff. The names below are the CONCEPTUAL block types, not the JSX
-tags — resolve every conceptual name to its exact tag + prop schema with the
-\`get-plan-blocks\` tool (see "Block reference" below) before authoring.
-
-- **Schema / migration change** → \`data-model\` for the resulting entities,
-  fields, and relations. Flag what moved per field/entity with
-  \`change: "added" | "modified" | "removed" | "renamed"\`, and for a changed type
-  set \`was\` to the prior value (e.g. the old column type) — grounded in the real
-  migration diff. That diff-aware \`data-model\` is the headline; reach for a split
-  \`diff\` of the literal SQL only when the exact statement still matters, not by
-  default.
-- **API / action / route change** → \`api-endpoint\` with the method, path,
-  params, request, and responses as they are after the change. Flag each changed
-  param/response with \`change\` (and \`was\` on a param whose type/shape changed),
-  and set \`change\` on the endpoint root for a wholly added or removed route. Mark
-  removed endpoints with \`deprecated: true\` and explain in prose.
-  Keep multiple API endpoints in the normal single-column document flow unless
-  they are an explicit before/after contract comparison.
-  Author each request/response example as a SINGLE valid JSON value — one
-  top-level object or array, parseable on its own — so it renders in the
-  collapsible JSON explorer. Do not put \`//\` or \`/* */\` comments, prose,
-  trailing commas, or two or more concatenated top-level objects inside one
-  example; a non-parseable body falls back to flat text and loses the explorer.
-  When an endpoint has several distinct message shapes (for example separate
-  websocket frame types, or a success body versus an error body), give each its
-  OWN example with its own label rather than cramming them into one body.
-- **Compatibility-sensitive change** → short \`rich-text\` notes beside the
-  relevant \`data-model\` / \`api-endpoint\` block. Name the changed field,
-  endpoint, or behavior and mark whether it is breaking, risky, or non-breaking;
-  pair that note with a split \`diff\` for the literal lines.
-- **Any meaningful code hunk** → \`diff\` with \`mode: "split"\`, carrying the real
-  \`before\` / \`after\` text and the \`filename\` / \`language\`. Split mode is the
-  default for recap code review because before/after legibility is the point;
-  use \`mode: "unified"\` only for a genuinely narrow standalone hunk where
-  side-by-side would hide the code. Give every \`diff\` a one-line \`summary\`
-  saying what the hunk changes and why; it renders as a description above the
-  code so the reviewer reads intent first. Never leave a diff unlabeled.
-  For the KEY changed files, attach \`annotations\` to the \`diff\` so the recap
-  calls out what each important hunk does — this is the headline affordance for
-  annotating the key files updated. Each annotation anchors to the AFTER-side
-  line numbers by default (set \`side: "before"\` to point at removed lines). Keep
-  it to a few high-signal notes per file, not one per line.
-  When several key files each need a substantial diff, introduce the group with a
-  \`rich-text\` heading block whose markdown is \`## Key changes\`, then place the
-  \`diff\` blocks under it in a reusable \`tabs\` block with horizontal orientation
-  (the default — omit \`orientation\`) so the selected file's split diff gets the
-  full document width. Let that heading label the section — do NOT also set a
-  \`title\` on the \`tabs\` block. Keep each tab label to the file path or a short
-  basename plus directory hint.
-  The renderer's wide document layout is intentionally allowlisted: \`diff\`,
-  \`annotated-code\`, vertical \`tabs\`, and \`tabs\` containing diff-like children
-  break out wider than prose. Do not put API endpoints, OpenAPI specs, data
-  models, JSON explorers, wireframes, question forms, or custom HTML into tabs
-  merely to make them wide.
-  If the recap ends with more than one supporting diff, that trailing diff
-  appendix should be one horizontal \`tabs\` block under its own \`## Key changes\`
-  heading, not a stack of separate \`diff\` blocks.
-- **Brand-new file or a substantial added block with no meaningful "before"** →
-  \`annotated-code\` rather than a one-sided split \`diff\`. Carry the real new code
-  with its \`filename\` / \`language\` and anchor a few high-signal notes to the lines
-  that matter so the reviewer reads what the new code does, not code for code's
-  sake. Keep split \`diff\` for true before/after hunks where the removed lines
-  still carry meaning, and group several annotated walkthroughs in a horizontal
-  \`tabs\` block the same way diffs are grouped.
-- **Files added / removed / renamed** → \`file-tree\` with each entry's \`change\`
-  flag (\`added\`, \`removed\`, \`modified\`, \`renamed\`) and a short \`note\`; attach a
-  \`snippet\` only when one tells the reviewer something the path does not.
-- **Rendered UI / interaction change** → one or more wireframes showing the
-  visible UI delta before the reviewer reads code. Use \`Before\` / \`After\`
-  wireframes when the comparison clarifies the change; otherwise use after-only
-  or a short state/flow sequence. Use realistic UI surfaces: for a popover
-  change, show a popover with its title row, top-right actions, options/fields,
-  tabs, selected/disabled states, people/lists/rows, and any opened prompt/menu
-  anchored to the correct trigger. If a route was added, show the route body and
-  the unavailable/empty state when the diff implements one. If permissions
-  changed, show what managers can do and what viewers/non-managers see instead.
-  Keep the body lean: the wireframe carries the UI story, while the file tree
-  and \`diff\` blocks carry implementation evidence.
-- **Architecture or data-flow shift** → \`diagram\` with \`data.html\` / \`data.css\`
-  as a two-panel before/after, layered, or swimlane layout, or \`mermaid\` for a
-  quick graph. Use two-dimensional layouts; do not reduce a structural change to
-  a left-to-right chain. Do not use \`diagram\` as a stand-in for rendered UI
-  controls; UI changes need \`wireframe\` blocks.
-  Author diagram HTML/CSS with the renderer-owned \`.diagram-*\` primitives
-  (\`.diagram-panel\`, \`.diagram-node\`, \`.diagram-pill\`, \`[data-rough]\`, …) and
-  the same \`--wf-*\` theme tokens \`references/wireframe.md\` defines — never
-  \`font-family\`, hex, rgb/hsl literals, or one-off dark/light palettes. Choose
-  the outer \`frame\` intentionally: recap diagrams usually benefit from
-  \`frame: "show"\` when they stand alone, but use \`frame: "hide"\` when columns,
-  tabs, a card, or the diagram's own panels already provide the boundary.
-- **Outcome-first narrative** → \`rich-text\` for the "what changed and why" prose:
-  the objective the diff served, the key decisions visible in it, and the risks a
-  reviewer should weigh. This is the only place the model writes freely.
-
-## Block reference — call \`get-plan-blocks\`, do not memorize tags
-
-The conceptual block names above (\`api-endpoint\`, \`data-model\`, \`json-explorer\`,
-\`tabs\`, …) are NOT the JSX tags you author with, and the exact tags, required
-fields, and prop shapes change as the block library evolves. Do not author from
-memorized tags — they drift and silently produce a wrong tag (\`ApiEndpoint\`
-instead of \`Endpoint\`, \`JsonExplorer\` instead of \`Json\`, \`Tabs\` instead of
-\`TabsBlock\`) that errors on import.
-
-**Before writing any structured plan content, fetch/read the block catalog.** In
-hosted or self-hosted mode, call \`get-plan-blocks\` on the Plan MCP connector
-(\`plan\` or legacy \`agent-native-plans\`). If no Plan tools are visible yet in a
-lazy-loading client, search/load them through the host's tool discovery surface
-first (\`tool_search\` when available). In local-files mode, or when the skill was
-installed as plain text and no MCP tools are registered after discovery, run
-\`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read that
-file first. The CLI command calls the public no-auth \`get-plan-blocks\` route and
-sends no plan/recap content. If network access is unavailable, use the bundled
-references and validate with \`plan local check\`; run \`plan local serve\` only
-when the hosted Plan UI is reachable or a local Plan app is already running.
-
-The catalog returns the authoritative, always-current block vocabulary generated
-live from the app's own block registry — the same config the renderer and MDX
-round-trip use — so it can never be stale even if this SKILL.md is an old
-installed copy:
-
-- \`get-plan-blocks\` (default \`format: "reference"\`) → a compact table of every
-  block's runtime \`type\`, exact MDX \`<Tag>\`, placement, and key data fields.
-  This is your map from each conceptual name above to its real tag and props.
-- \`get-plan-blocks\` with \`format: "schema"\` → the full per-block JSON Schema
-  plus a worked example for each block, when you need exact field types,
-  enums, or nesting (e.g. \`Diff.annotations\`, \`Endpoint.params[].in\`,
-  \`DataModel.entities[].fields[]\`).
-
-Author the recap source against the tags and schemas that call returns. The
-complete set of valid block-level tags is whatever \`get-plan-blocks\` lists;
-any other capitalized tag at the block level is rejected on import with an
-"Unknown plan block" / "did you mean" error. Lowercase HTML tags inside
-\`rich-text\`/markdown prose (\`<div>\`, \`<span>\`, \`<code>\`, \`<br>\`, …) are always
-fine — only capitalized component-style block tags are validated.
-
-A few recap-specific authoring rules the registry table cannot encode:
-
-- Every structured block takes a REQUIRED \`id\` (unique across the whole plan)
-  plus the shared optional \`summary\` / \`editable\` envelope. Ordinary top-level
-  Markdown prose imports as rich-text automatically; use \`<RichText id="...">\`
-  only when prose needs explicit metadata or a preserved referenced block id.
-- Every capitalized block component must be self-closing (\`<Diagram ... />\`) or
-  explicitly closed around children (\`<RichText ...>...</RichText>\`). Never
-  leave a bare opening tag like \`<RichText ...>\` in a paragraph; MDX treats it
-  as unclosed JSX and import fails before the recap can render.
-- Code-bearing blocks (\`Code\`, \`AnnotatedCode\`, and \`Diff\`) are
-  whitespace-sensitive. Prefer the exact MDX form from the \`get-plan-blocks\`
-  examples / source exporter, where multiline code is encoded as JSON string
-  attributes such as \`code={"const x =\\n  y"}\`. Static template literals are
-  accepted only when they are static strings with no \`\${...}\` interpolation.
-- \`Endpoint\`: prose \`description\` is the MDX **children** (body between the
-  tags), not an attribute; for a WebSocket upgrade use \`method="GET"\`. Each
-  request/response \`example\` is a JSON **string** (the renderer parses it into
-  the JSON explorer), so keep it a single parseable JSON value.
-- \`TabsBlock\`: the whole \`tabs\` array (including nested child blocks) is ONE
-  JSON \`tabs={[…]}\` prop — there is NO nested \`<Tab>\` element.
-- \`WireframeBlock\`: its body is a single \`<Screen surface ... html=… />\` subtree
-  (nested MDX, not a flat prop); \`html\` must be a single-quoted string or static
-  template literal, never a dynamic \`html={someVar}\` expression. See
-  \`references/wireframe.md\` for the HTML rules.
-- \`Diagram\`: the whole payload is one \`data={{ html?, css?, nodes?, edges?, … }}\`
-  attribute and requires either \`html\` or at least one node; \`Mermaid\` is its
-  own separate block (\`source\` text), not a \`Diagram\` prop.
-
-## Before / After Is The Headline
-
-The recap's center of gravity is the before/after comparison. For document-body
-comparisons there are two primitives, and they cover the whole need together:
-
-- **\`columns\`** — the side-by-side container, for **structured** comparisons.
-  Use two columns labeled \`Before\` and \`After\`, each holding a block (commonly a
-  \`data-model\`, \`api-endpoint\`, or \`rich-text\`), so the reviewer reads the old
-  shape against the new shape in one glance. This is the right primitive for
-  "the schema went from X to Y" or "the endpoint contract changed like this."
-  Do not use \`columns\` simply to compact or group a list of API endpoints.
-- **\`diff\`** — for **code**. It renders the literal removed and added lines. Use
-  it for the actual hunks. Use split mode by default for recap code review;
-  reserve \`mode: "unified"\` for genuinely narrow standalone hunks where
-  side-by-side would hide the code. Key-file diff groups should use horizontal
-  tabs so split diffs get the full document width.
-
-For UI diffs, wireframes are the visual comparison primitive. Use before/after
-wireframes when the comparison clarifies the change; use after-only or a state
-sequence when that better matches the change. The visual headline must show
-exact placement, realistic chrome, and adequate padding before any abstract
-explanation. Do not stop at the first visible affordance when the diff adds a
-flow; show the entry point, the opened surface, and the resulting state or page
-so the reviewer can trace the actual user path. \`references/wireframe.md\` owns
-the before/after layout choice —
-the \`columns\` renderer keeps narrow surfaces side by side and auto-stacks wide
-\`desktop\`/\`browser\` frames vertically; never hand-build a side-by-side
-wireframe layout in \`custom-html\`. For document-body
-comparisons, there is no other multi-column primitive — \`columns\` plus the
-\`diff\` block are the whole comparison vocabulary. Do not hand-build side-by-side
-layouts in \`custom-html\`, and do not stack two \`data-model\` blocks vertically
-and call it a comparison when \`columns\` exists to put them side by side.
-
-## Grounding Rule
-
-Structured blocks are **true by construction** only if they are derived from the
-actual changed lines. The \`diff\`, \`data-model\`, \`api-endpoint\`, and \`file-tree\`
-blocks MUST be built mechanically from the real diff — real paths, real fields,
-real method/path, real before/after text — never inferred, rounded, or invented.
-The model writes only the prose: the "why", the narrative, the risk read. A
-confidently wrong recap is dangerous in a review context, because a reviewer who
-trusts the summary may skip the very line the summary got wrong. When the diff
-does not contain a fact, leave it out rather than guess; mark anything the model
-inferred (not extracted) as inferred in prose.
-
-## Security
-
-- **Gate visibility.** Recaps of a private repo are org/login-gated — set the
-  plan's visibility to the owning org or login, never auto-public. A recap can
-  expose unreleased schema, internal endpoints, and architecture; treat it like
-  the source it summarizes. Any PR comment or handoff that links to the recap
-  must say that private-repo recaps require signing in with access to the owning
-  org if the link does not load.
-- **Never transcribe secrets.** A diff can contain API keys, tokens, webhook
-  URLs, signing secrets, \`.env\` values, or credential-looking literals. Do not
-  copy any of these into a \`diff\`, \`file-tree\` snippet, \`api-endpoint\`, or prose
-  block — redact them (\`sk-•••\`, \`<redacted>\`). This mirrors the repo's
-  hardcoded-secret rule: obviously fake placeholders only, never the real value,
-  in any block, caption, or note.
-
-## Bidirectional Loop
-
-In hosted mode, because a recap is a real, editable plan, the same review loop
-as forward plans applies: a reviewer can annotate any block, and the coding
-agent reads \`get-plan-feedback\` to drive fixes back into the code — annotation →
-agent → diff, the same close-the-loop flow forward plans use. After a reviewer
-annotates a block, call \`get-plan-feedback\` to read the structured feedback,
-then either update the recap with \`create-visual-recap\` (passing the existing
-\`planId\` to replace it in place) or apply targeted changes with
-\`update-visual-plan\`. The loop is live and wired. In local-files privacy mode,
-do not call those hosted tools; read review notes from chat or local files, edit
-\`<plan-dir>/*.mdx\` directly, and rerun \`plan local check\`, \`serve\`, or \`verify\`
-for \`<plan-dir>\`. The one thing not yet automatic is PR-comment-triggered
-re-runs: the GitHub Action creates an initial recap per PR, but it does not yet
-re-run automatically when new review feedback is posted in GitHub — that
-auto-re-run is the remaining fast-follow.
-
-## Related Skills
-
-- **visual-plan** — the canonical command and the source of the shared Wireframe
-  & Canvas and Document Quality cores; a recap follows the same block discipline
-  in reverse.
-- **comment anchors** — recap comments use the same anchor rules as forward
-  plans; see "Interpreting comment anchors" in the visual-plan skill for
-  coordinate frames, wireframe node ids, text-quote resolution, detached
-  threads, routing via \`resolutionTarget\`, and two-axis consumed/resolved state.
-- **security** — data scoping, secret handling, and the hardcoded-secret rule the
-  recap's redaction and visibility gating mirror.
-- **sharing** — org/login-gated visibility for the plan that holds the recap.
-`;
-export const VISUALIZE_REPO_SKILL_MD = `---
-name: visualize-repo
-description: >-
-  Open or create a repo-native visual documentation workspace backed by local
-  Plan MDX files. Use when the user asks to visualize a repository, create
-  durable visual docs for APIs/components/models/flows, launch a visual repo
-  viewer, review repo docs like a visual IDE, or collect Plan comments that
-  should become coding-agent changes.
-metadata:
-  visibility: exported
----
-
-# Visualize Repo
-
-\`/visualize-repo\` opens a local, source-controlled visual documentation layer
-for a repository. It is for durable repo understanding, not a one-off plan:
-components can have wireframes, APIs can have specs, models can have schema
-views, and reviewers can comment on those docs before sending work to a coding
-agent.
-
-## Default Command
-
-Run the Agent-Native CLI from the repo root:
-
-\`\`\`bash
-npx @agent-native/core@latest visualize-repo --open
-\`\`\`
-
-Useful variants:
-
-\`\`\`bash
-npx @agent-native/core@latest visualize-repo init
-npx @agent-native/core@latest visualize-repo --target actions --target server/db/schema.ts
-npx @agent-native/core@latest visualize-repo check
-npx @agent-native/core@latest visualize-repo verify
-npx @agent-native/core@latest visualize-repo --no-open
-\`\`\`
-
-The command writes or updates \`agent-native.json\` with an
-\`apps.visualize-repo\` local-files section, creates a starter MDX folder at
-\`.agent-native/visual-docs/repo-overview\`, then serves it through the Plan
-local bridge. The hosted Plan UI can render the review surface, but the plan
-source stays in local files and bridge comments stay in \`comments.json\`.
-
-## When There Is No Manifest
-
-If \`agent-native.json\` does not exist, let the CLI bootstrap one. It scans for
-high-value starting points such as \`actions/\`, \`app/components/\`,
-\`app/pages/\`, \`server/db/schema.ts\`, \`src/\`, \`packages/\`, \`templates/\`,
-\`docs/\`, and \`content/\`. Keep the first run targeted. Prefer 5-20 visualized
-nodes over a generated wall of repo prose.
-
-Use explicit targets when the user already knows the important surface:
-
-\`\`\`bash
-npx @agent-native/core@latest visualize-repo \\
-  --target actions/webhooks.ts \\
-  --target server/db/schema.ts \\
-  --target app/components/PromptComposer.tsx
-\`\`\`
-
-## Agent Workflow
-
-1. Inspect \`agent-native.json\` and the generated \`plan.mdx\`.
-2. Read the source anchors listed for each target before changing the visual
-   docs.
-3. Add only the visual blocks that earn their keep: \`api-endpoint\` for stable
-   APIs, \`data-model\` for durable schema, \`wireframe\` for user-facing
-   components/flows, \`diagram\` for architecture, and \`annotated-code\` for
-   load-bearing implementation.
-4. Run \`npx @agent-native/core@latest visualize-repo check\` after editing MDX.
-5. Use \`verify\` before handoff when renderer correctness matters.
-
-When acting on comments, treat local \`comments.json\` as the feedback inbox.
-Agent-targeted comments should become code changes plus matching MDX updates so
-the visual docs and executable code stay in sync.
-
-## Privacy Boundary
-
-\`visualize-repo check\` is local/offline lint. \`visualize-repo --open\` starts a
-localhost bridge and opens the Plan UI against local files; it does not publish
-the plan to hosted storage and performs no hosted Plan database writes.
-\`visualize-repo verify\` may send the MDX folder to the Plan app's public
-validation action so the real renderer schema can check it. For no hosted
-content egress, pass \`--app-url\` pointing at a local Plan app or skip
-\`verify\` and rely on \`check\`.
-
-Do not call hosted Plan write tools for this workflow unless the user explicitly
-asks to publish or share the docs. Avoid \`create-visual-plan\`,
-\`update-visual-plan\`, \`import-visual-plan-source\`, \`patch-visual-plan-source\`,
-and \`get-plan-feedback\` for local repo docs; edit the MDX files directly and
-use the local bridge.
-`;
+export { CANVAS_REFERENCE_MD, CONNECTION_REFERENCE_MD, DOCUMENT_QUALITY_REFERENCE_MD, EXEMPLAR_REFERENCE_MD, LOCAL_FILES_REFERENCE_MD, VISUAL_PLANS_SKILL_MD, VISUAL_RECAP_SKILL_MD, VISUALIZE_REPO_SKILL_MD, WIREFRAME_REFERENCE_MD, };
 export const BUILT_IN_APP_SKILLS = {
     assets: {
         skillName: "assets",