@agent-native/core 0.79.26 → 0.80.0

package/corpus/core/src/cli/skills.ts

@@ -37,15 +37,16 @@ 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-plan|visual-recap|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-plan|visual-recap|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-plan|visual-recap|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 status [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|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|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|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 visual-recap --with-github-action
@@ -376,6 +377,92 @@ iteration, or a human-in-the-loop choice among design directions.
   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.
+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 like
+  Figma 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.
+
+## Required Local Bridge
+
+From the target app repo, make sure its dev server is running, then run:
+
+\`\`\`bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+\`\`\`
+
+Use the app's real port. The command starts a local bridge on
+\`http://127.0.0.1:7331\` by default and exposes \`/manifest.json\`,
+\`/routes.json\`, and \`/health\`.
+
+For one-shot agent setup, ask for JSON and keep the long-running bridge open in
+a second terminal if the user needs live updates:
+
+\`\`\`bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+\`\`\`
+
+## Action Flow
+
+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\`:
+
+\`\`\`bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "connectionId": "<connection-id>",
+  "paths": ["/", "/pricing", "/checkout?step=payment"]
+}'
+\`\`\`
+
+If no \`routes\` or \`paths\` are supplied, \`add-localhost-screens\` uses every
+route from the latest localhost manifest.
+
+4. Navigate to overview mode:
+
+\`\`\`bash
+pnpm action navigate --view editor --designId "<design-id>" --editorView overview
+\`\`\`
+
+## 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.
+
+## 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
@@ -526,6 +613,27 @@ themes. For any inline border, background, or text color, reference a token:
 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.** \`.wf-card\` and \`.wf-box\` already render with
+theme-safe filled backgrounds (\`--wf-card\`) and soft tokenized borders that work
+in both light and dark mode. 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. The renderer sketches the outer frame and
+standard controls by default; 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
@@ -1064,7 +1172,11 @@ 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.
+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 -->`;
 
@@ -1185,6 +1297,146 @@ const EXEMPLAR_REFERENCE_POINTER = `For a worked example of the bar — a great
 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\` validates these required fields against the
+  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,
+  prints diagnostics, and exits. 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: >-
@@ -1306,24 +1558,15 @@ skill's review discipline. Do not advise the user to skip \`/visual-plan\` becau
 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. NEVER hand the plan over
-as inline chat content — no Markdown prose, ASCII sketch, table, or fenced
-wireframe. Some clients lazy-load connector tools through a deferred tool
-registry instead of showing the \`plan\` 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_ui_plan\`, or
-\`get_plan_blocks\`, then use the Plan MCP tools it exposes. If the connector's
-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 auth. Stop and give the user the exact restore step
-for their current client: in Codex/Codex Desktop run
-\`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
-and start a new Codex session; in Claude Code run \`/mcp\` and choose
-Authenticate/Reconnect (or run the same reconnect command with
-\`--client claude-code\` and restart Claude). Auth is stored per client
-config/session, so one client's reconnect does not make another running client
-load tools. Never reinstall from scratch just to fix auth. Publish once the tool
-is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
+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
 
@@ -1559,69 +1802,19 @@ directory before authoring a plan.
 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
+## Local-Files Privacy Mode — read \`references/local-files.md\`
 
-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
-planning, repo-owned/source-controlled planning artifacts, or when
-\`AGENT_NATIVE_PLANS_MODE=local-files\` is set. Also use it when a user or repo
-policy says a plan must stay under their own brand, domain, source control, or
-infrastructure. In this mode the plan data must never be sent to the Plan MCP
-server or Plan app action surface. Schema-only block catalog lookup is allowed
-because 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.
-
-The local-files contract is:
-
-- Read source context from local files and shell commands only.
-- Fetch/read the block catalog before writing structured MDX. The
-  \`plan blocks\` command calls the public no-auth \`get-plan-blocks\` route and
-  writes only registry metadata to disk; use \`--format schema\` if exact nested
-  fields are needed. If network access is unavailable, use the bundled
-  references and rely on \`plan local check\` / \`plan local serve\` to catch
-  invalid tags. For \`checklist\` and \`question-form\`, copy the catalog examples
-  verbatim: checklist items need \`id\` and \`label\`; question-form questions need
-  \`id\`, \`title\`, and \`mode\`; and each option needs \`id\` and \`label\`. \`plan local
-  check\` validates these required fields against the renderer schema.
-- Write the plan as a local MDX folder: use \`plans/<slug>/\` when the user
-  wants the artifact checked into the repo, or use 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 contains \`plan.mdx\`, optional
-  \`canvas.mdx\`, optional \`prototype.mdx\`, and optional \`.plan-state.json\`. Use
-  that exact chosen folder as \`<plan-dir>\` in every local CLI command below.
-- Run \`npx @agent-native/core@latest plan local check --dir <plan-dir>\` before
-  serving, then run
-  \`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind plan --open\`.
-  Report the returned 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.
-- For headless verification, run
-  \`npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind plan\`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
-  the \`bridgeUrl\` from the verify/serve JSON to read the concrete validation
-  error.
-- Do **not** call \`create-visual-plan\`, \`create-ui-plan\`,
-  \`create-prototype-plan\`, \`create-plan-design\`, \`import-visual-plan-source\`,
-  \`update-visual-plan\`, \`patch-visual-plan-source\`, \`get-plan-feedback\`,
-  \`export-visual-plan\`, or any hosted Plan tool for that plan except the
-  schema-only block catalog lookup above.
-- Treat feedback as file or chat feedback: update the MDX files directly, rerun
-  the local bridge command, and summarize the new local bridge URL. Hosted
-  comments, sharing, history, and publish/export receipts are unavailable until
-  the user explicitly opts into publishing.
-
-Local-files mode prevents plan content from going to the Agent-Native Plan
-database. It does not by itself make the coding agent's language model local;
-for that stronger privacy boundary, the host agent/model must also be local or
-otherwise approved by the user.
+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
 
@@ -1701,17 +1894,9 @@ For fully offline, no-account use, run the Plans app locally and sync plans to
 your repo as MDX. This local mode is a separate advanced path, not the default
 hosted flow.
 
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. 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.
+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.
@@ -1738,110 +1923,33 @@ schema, API, file, and architecture changes become the same \`data-model\`,
 now they summarize work that exists. A reviewer scans the shape of the change
 before spending attention on the literal lines.
 
-## Local-Files Privacy Mode Exception
-
-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
-recaps, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. This is the only
-exception to the hosted publish rule below.
-
-In local-files mode:
-
-- Read the diff/stat/source context from local files and shell commands only.
-  The existing \`npx @agent-native/core@latest recap collect-diff\`, \`scan\`, and
-  \`build-prompt --local-files\` helpers are safe to use because they operate on
-  local files and do not write to the Plan database.
-- Fetch/read the block catalog before writing structured MDX. Use
-  \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` when the Plan
-  MCP connector is not registered; it calls the public no-auth
-  \`get-plan-blocks\` route and sends no recap content. If network access is
-  unavailable, use the bundled references and validate the MDX with
-  \`plan local check\`; do not run \`plan local serve\` unless the hosted Plan UI is
-  reachable or a local Plan app is already running. For \`checklist\` and \`question-form\`,
-  copy the catalog examples verbatim: checklist items need \`id\` and \`label\`;
-  question-form questions need \`id\`, \`title\`, and \`mode\`; and each option needs
-  \`id\` and \`label\`. \`plan local check\` validates these required fields against
-  the renderer schema.
-- Write the recap as a local MDX folder: use \`plans/<slug>/\` when the user
-  wants the artifact checked into the repo, or use 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 contains \`plan.mdx\`, optional
-  \`canvas.mdx\`, optional \`prototype.mdx\`, and optional \`.plan-state.json\`. Set
-  \`kind: "recap"\` and \`localOnly: true\` in frontmatter/state when authoring the
-  source. Use that exact chosen folder as \`<plan-dir>\` in every local CLI command
-  below.
-- Run \`npx @agent-native/core@latest plan local check --dir <plan-dir>\` before
-  any preview. When the hosted Plan UI is reachable, run
-  \`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open\`.
-  Report the returned 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 local \`<plan-dir>\`
-  path after \`plan local check\` and note that interactive preview requires either
-  network access to the hosted Plan UI or a running local Plan app.
-- For headless verification, run
-  \`npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind recap\`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
-  the \`bridgeUrl\` from the verify/serve JSON to read the concrete validation
-  error.
-- Do **not** call \`create-visual-recap\`, \`create-visual-plan\`,
-  \`import-visual-plan-source\`, \`update-visual-plan\`,
-  \`patch-visual-plan-source\`, \`get-plan-feedback\`, \`export-visual-plan\`,
-  \`set-resource-visibility\`, or any hosted Plan tool for that recap except the
-  schema-only block catalog lookup above.
-- Treat review feedback as file or chat feedback: update the MDX files directly,
-  rerun \`plan local check\`, and rerun \`serve\` or \`verify\` only when that preview
-  path is available. Summarize the new local URL when one exists; otherwise
-  summarize the checked local folder path.
-  Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
-  publishing are unavailable until the user explicitly opts into publishing.
-
-Local-files mode prevents recap content from going to the Agent-Native Plan
-database. It does not by itself make the coding agent's language model local;
-for that stronger privacy boundary, the host agent/model must also be local or
-otherwise approved by the user.
-
-## Always Publish As An Agent-Native Plan — Never Inline
-
-The deliverable is ALWAYS a published Agent-Native Plan, created with the
-\`create-visual-recap\` tool on the Plan MCP connector. The connector is usually
-exposed as the \`plan\` server, but older installed agents may expose the same
-hosted connector as \`agent-native-plans\`; both names are valid. NEVER hand the
-recap to the user as inline chat content — not Markdown prose, not an ASCII
-sketch, not a table, not a fenced "wireframe", not a "here's the recap" summary.
-A recap's entire value is the hosted, interactive, annotatable plan; an inline
-summary is not a recap, it is the thing a recap replaces. The only supported
-output is to publish the plan and return its absolute URL.
-
-Some clients lazy-load connector tools through a deferred tool registry instead
-of showing the \`plan\` namespace upfront. Before declaring the Plan connector
-missing, search/load tools with the host's discovery surface (\`tool_search\` when
-available) for \`create_visual_recap\`, \`create_visual_plan\`, or
-\`get_plan_blocks\`, then use the Plan MCP tools it exposes.
-
-Except for the explicit local-files privacy mode above, if neither the \`plan\`
-nor legacy \`agent-native-plans\` Plan MCP tools are available after deferred tool
-discovery, do NOT improvise an inline recap as a fallback. Do not report the
-connector as disconnected just because it is named \`agent-native-plans\` instead
-of \`plan\`, or because the tools were not visible before discovery. 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
-authenticate. Stop and tell the user how to restore it for their current client: in
-Codex/Codex Desktop, run
-\`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
-and start a new Codex session; in Claude Code, run \`/mcp\` and choose
-Authenticate/Reconnect, or run the reconnect command with \`--client claude-code\`
-and restart Claude. Auth is stored per client config/session; \`--client all\`
-refreshes every local client config that already has the Plan entry, but each
-running client still has to reload its MCP tools. Reconnect re-authenticates
-WITHOUT reinstalling and finds the entry by URL regardless of connector name.
-Never reinstall from scratch just to fix auth. Then publish once the tool is
-reachable. Falling back to inline content is a defect, not a degraded mode.
+## 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
 
@@ -2229,6 +2337,11 @@ A few recap-specific authoring rules the registry table cannot encode:
   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
@@ -2432,6 +2545,9 @@ export const BUILT_IN_APP_SKILLS = {
   },
   design: {
     skillName: "design-exploration",
+    extraSkills: {
+      "visual-edit": DESIGN_VISUAL_EDIT_SKILL_MD,
+    },
     manifest: normalizeAppSkillManifest({
       schemaVersion: 1,
       id: "design",
@@ -2454,6 +2570,11 @@ export const BUILT_IN_APP_SKILLS = {
           action: "present-design-variants",
           path: "/design",
         },
+        {
+          id: "visual-edit",
+          action: "add-localhost-screens",
+          path: "/design",
+        },
       ],
       skills: [
         {
@@ -2461,6 +2582,11 @@ export const BUILT_IN_APP_SKILLS = {
           visibility: "exported",
           exportAs: "design-exploration",
         },
+        {
+          path: "skills/visual-edit",
+          visibility: "exported",
+          exportAs: "visual-edit",
+        },
       ],
       hostAdapters: [
         "codex-plugin",
@@ -2489,8 +2615,14 @@ export const BUILT_IN_APP_SKILLS = {
         "references/canvas.md": CANVAS_REFERENCE_MD,
         "references/document-quality.md": DOCUMENT_QUALITY_REFERENCE_MD,
         "references/exemplar.md": EXEMPLAR_REFERENCE_MD,
+        "references/connection.md": CONNECTION_REFERENCE_MD,
+        "references/local-files.md": LOCAL_FILES_REFERENCE_MD,
+      },
+      "visual-recap": {
+        "references/wireframe.md": WIREFRAME_REFERENCE_MD,
+        "references/connection.md": CONNECTION_REFERENCE_MD,
+        "references/local-files.md": LOCAL_FILES_REFERENCE_MD,
       },
-      "visual-recap": { "references/wireframe.md": WIREFRAME_REFERENCE_MD },
     },
     manifest: normalizeAppSkillManifest({
       schemaVersion: 1,
@@ -2621,6 +2753,9 @@ const BUILT_IN_APP_SKILL_ALIASES = {
   "ui-design": "design",
   "ux-design": "design",
   "design-exploration": "design",
+  "visual-edit": "design",
+  "local-visual-edit": "design",
+  "design-visual-edit": "design",
   "ux-exploration": "design",
   "agent-native-design": "design",
   "agent-native-design-exploration": "design",
@@ -2654,6 +2789,8 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
   ],
   design: [
     "design-exploration",
+    "visual-edit",
+    "local-visual-edit",
     "ux-exploration",
     "agent-native-design-exploration",
   ],
@@ -3085,6 +3222,19 @@ function builtInOnlySkillNames(target: string): string[] | undefined {
   if (normalized === "visual-recap" || normalized === "visual-recaps") {
     return ["visual-recap"];
   }
+  if (
+    normalized === "design-exploration" ||
+    normalized === "agent-native-design-exploration"
+  ) {
+    return ["design-exploration"];
+  }
+  if (
+    normalized === "visual-edit" ||
+    normalized === "local-visual-edit" ||
+    normalized === "design-visual-edit"
+  ) {
+    return ["visual-edit"];
+  }
   return undefined;
 }
 
@@ -4246,6 +4396,11 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS: SkillsTargetPromptContext["options"] = [
     label: "design-exploration",
     hint: BUILT_IN_APP_SKILLS.design.manifest.description,
   },
+  {
+    value: "visual-edit",
+    label: "visual-edit",
+    hint: "Open a running local app in Design overview mode as URL-backed iframe screens.",
+  },
   {
     value: "context-xray",
     label: "context-xray",