@agent-native/core 0.44.4 → 0.45.1

package/dist/cli/skills.js

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { buildAppSkillPack, ensureAppSkill, loadAppSkillManifest, normalizeAppSkillManifest, } from "./app-skill.js";
 import { readConnectClientPreferences, resolveClients, runConnect, writeConnectClientPreferences, } from "./connect.js";
 import { CONTEXT_XRAY_SKILL_MD, installLocalContextXray, } from "./context-xray-local.js";
@@ -16,6 +17,8 @@ const HELP = `agent-native skills
 
 Usage:
   agent-native skills list
+  agent-native skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--json]
+  agent-native skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--dry-run] [--json]
   agent-native skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
   agent-native skills add <manifest-or-app-dir> [--client ...] [--yes]
 
@@ -24,6 +27,8 @@ Examples:
   agent-native skills add design-exploration
   agent-native skills add visual-plan
   agent-native skills add visual-plan --with-github-action
+  agent-native skills status visual-plan
+  agent-native skills update visual-plan
   agent-native skills add visual-plan --no-connect
   agent-native skills add context-xray --client all
   agent-native skills add assets --client claude-code
@@ -45,7 +50,15 @@ register the connector without authenticating (leave auth to the host or run
 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.`;
+bundles and custom adapter output.
+
+When installing visual-plan interactively, the CLI offers to add the optional PR
+Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
+run "agent-native recap setup" / "agent-native recap doctor" to configure and
+verify GitHub Actions.
+
+The status/update commands inspect copied Agent Native skill folders and refresh
+their instruction files from the current @agent-native/core package.`;
 const ASSETS_SKILL_MD = `---
 name: assets
 description: >-
@@ -198,8 +211,7 @@ iteration, or a human-in-the-loop choice among design directions.
 `;
 /**
  * Shared setup/auth block for every Plans skill (`/visual-plan`,
- * `/visual-recap`, `/ui-plan`, `/prototype-plan`, `/plan-design`,
- * `/visual-questions`). Interpolated into each skill markdown
+ * `/visual-recap`). Interpolated into each skill markdown
  * so the install + one-step authenticate instructions never drift between them.
  * Keep this in sync with the copies under `templates/plan/.agents/skills/*` and
  * top-level `skills/*` (this skill's SKILL.md is triplicated with no sync test).
@@ -217,10 +229,12 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/visual-recap\`, \`/ui-plan\`,
-\`/prototype-plan\`, \`/plan-design\`, \`/visual-questions\`) generate a plan and open
-the editor. Pass \`--no-connect\` to
-register the connector without authenticating, then run
+After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
+commands. Other planning modes — UI-first (\`create-ui-plan\`), prototype-first
+(\`create-prototype-plan\`), design-first (\`create-plan-design\`), and visual
+intake (\`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
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
 **Browser (people you share with).** Open the Plans editor and create & edit
@@ -249,13 +263,13 @@ not put shared secrets in skill files.`;
 // distributed artifact stays a flat string, so distribution is unchanged.
 //
 // Consumers:
-//   WIREFRAME_QUALITY_CORE  — visual-plan, ui-plan, visual-recap (surface-agnostic)
-//   CANVAS_SURFACE_CORE     — visual-plan, ui-plan (canvas/artboard mechanics)
-//   DOCUMENT_QUALITY_CORE   — visual-plan, ui-plan
-//   EXEMPLAR_CORE           — visual-plan, ui-plan
+//   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 /
-// ui-plan). Do not put canvas/artboard placement mechanics here.
+// 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
@@ -476,7 +490,34 @@ hex colors:
 \`\`\`
 
 <!-- SHARED-CORE:wireframe-quality END -->`;
-// Canvas/artboard placement mechanics. Used only by visual-plan and ui-plan
+// 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 -->
 
@@ -693,7 +734,7 @@ unreadable diagrams before asking for approval.
 <!-- SHARED-CORE:document-quality END -->`;
 const EXEMPLAR_CORE = `<!-- SHARED-CORE:exemplar START -->
 
-**GOOD.** A \`/ui-plan\` for a todo app: a canvas with a \`desktop\` artboard whose
+**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
@@ -733,6 +774,60 @@ labeled boxes with overlapping text, where the actual code evidence and
 recommendations live elsewhere. 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: artboard
+placement is locked by the \`surface\` (never coordinates), 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 VISUAL_PLANS_SKILL_MD = `---
 name: visual-plan
 description: >-
@@ -754,14 +849,14 @@ usually start in the document with local diagrams near each claim. UI and produc
 plans should still start with the top canvas/prototype when screens or behavior
 are what the user needs to review.
 
-\`/visual-plan\` is the canonical command and the main entry point. Use \`/ui-plan\`
-when the work is primarily product UI and review should start with the screens.
-Use \`/prototype-plan\` when review should start with a functional live prototype.
-Use \`/plan-design\` when review should start with full-fidelity branded design.
-Use \`/visual-questions\` only when the user explicitly wants a visual intake form
-before planning. When a Codex, Claude Code, Markdown, or pasted plan already
-exists, \`/visual-plan\` uses that source plan as the starting point and builds
-the review surface from it instead of starting over.
+\`/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
 
@@ -814,6 +909,37 @@ plan needs a richer review surface.
   update the plan with \`update-visual-plan\` rather than only changing course in
   chat, and re-read the approved plan before major steps.
 
+## Local-Files Privacy Mode
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+planning, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. In this mode the
+plan data must never be sent to the Plan MCP server or Plan app action surface.
+
+The local-files contract is:
+
+- Read source context from local files and shell commands only.
+- Write the plan as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
+  \`.plan-state.json\`.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind plan\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- 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.
+- Treat feedback as file or chat feedback: update the MDX files directly, rerun
+  the local preview command, and summarize the new local URL/path. 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.
+
 ## Core Workflow
 
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
@@ -908,38 +1034,30 @@ not add visual chrome by default:
   needs to operate the behavior. Keep the static wireframes in
   \`content.canvas\`, add the aligned functional prototype in
   \`content.prototype\`, and rely on the top visual tabs to switch between them.
-- **Prototype-first** when the user explicitly asks for \`/prototype-plan\`, asks
-  to operate the UI, or when interaction is the main question. Use
-  \`create-prototype-plan\`, which still preserves static mocks where useful.
+- **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 & Canvas Core
+## Wireframe quality — read \`references/wireframe.md\`
 
-This section is shared by \`/visual-plan\` and \`/ui-plan\`, and is the single
-source of truth for how wireframes and the canvas work. The wireframe-quality
-rules below are additionally shared, word for word, with \`/visual-recap\`; the
-canvas/artboard mechanics apply only to \`/visual-plan\` and \`/ui-plan\`. Do not
-paraphrase any of it per command.
+${WIREFRAME_REFERENCE_POINTER}
 
-${WIREFRAME_QUALITY_CORE}
+## Canvas — read \`references/canvas.md\`
 
-${CANVAS_SURFACE_CORE}
+${CANVAS_REFERENCE_POINTER}
 
-## Document Quality Core
+## Document quality — read \`references/document-quality.md\`
 
-This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
-the single source of truth for the document below the canvas. Do not paraphrase
-it per command.
+${DOCUMENT_QUALITY_REFERENCE_POINTER}
 
-${DOCUMENT_QUALITY_CORE}
+## Good vs. bad exemplar — read \`references/exemplar.md\`
 
-## Good vs. Bad Exemplar
-
-${EXEMPLAR_CORE}
+${EXEMPLAR_REFERENCE_POINTER}
 
 ## Tool Guidance
 
@@ -953,8 +1071,8 @@ ${EXEMPLAR_CORE}
   optional matching Prototype tab.
 - \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
   into a prototype plan.
-- \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
-  command, not as \`/visual-plan\` preflight.
+- \`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; prefer
   \`contentPatches\` over regenerating the whole plan.
 - \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
@@ -967,177 +1085,22 @@ ${EXEMPLAR_CORE}
 - \`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.
 
-## Setup & Authentication
-
-There are two ways into Plans.
-
-**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
-installs the Plans skills, registers the hosted Plans MCP connector, and
-authenticates it in the same step (a one-time browser sign-in at setup — this is
-intended), so the first tool call does not hit an OAuth wall:
-
-\`\`\`bash
-agent-native skills add visual-plan
-\`\`\`
-
-After that, \`/visual-plan\` (and \`/visual-recap\`, \`/ui-plan\`,
-\`/prototype-plan\`, \`/plan-design\`, \`/visual-questions\`) generate a plan and open
-the editor. Pass \`--no-connect\` to
-register the connector without authenticating, then run
-\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
-
-**Browser (people you share with).** Open the Plans editor and create & edit
-with no sign-up — you work as a guest. Sign in only when you want to save or
-share; signing in claims the plans you made as a guest into your account.
-
-Sharing and commenting require an account: public/shared plans are viewable by
-anyone with the link, but commenting on them needs an agent-native account.
-
-For fully offline, no-account use, run the Plans app locally and sync plans to
-your repo as MDX. This local mode is a separate advanced path, not the default
-hosted flow.
-
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. Authenticate the connector with
-\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
-instead re-run /mcp and choose Authenticate), then continue once the connector
-is available.
-
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
-not put shared secrets in skill files.
-`;
-export const UI_PLAN_SKILL_MD = `---
-name: ui-plan
-description: >-
-  Use Agent-Native Plans for UI-first planning with an optional top pan/zoom
-  wireframe canvas, a refined Notion-like document, rich tabs, diagrams,
-  comments, drawing, and agent handoff.
-metadata:
-  visibility: exported
----
-
-# UI Plan
-
-Use \`/ui-plan\` when the task is primarily about product UI, user flows,
-interaction details, component layout, or visual direction. The reviewable UI
-comes first; implementation detail comes after the user has something concrete to
-react to.
-
-\`/visual-plan\` remains the general command for architecture, backend, refactors,
-and mixed work. Use \`/prototype-plan\` when the UI review needs a functional live
-prototype instead of static screens. Use \`/plan-design\` when polish, brand, or
-visual fidelity are material to the decision. Use \`/visual-questions\` only when
-the user explicitly wants visual intake before planning. Use \`/visual-plan\` when
-a text plan already exists and should become the source material for the review.
-
-## Plan Discipline
-
-- **Gate hard.** Use a UI plan when the surface is new, ambiguous, spans several
-  screens or states, or the direction needs agreement before coding. Skip it for
-  cosmetic one-liners — a color, a label, a spacing tweak — and just make the
-  change. Never ship a single-step or filler plan.
-- **Research before you draft.** Read the real components, routes, and design
-  tokens first; ground every mockup and the file map in actual files and symbols.
-  Delegate wide exploration to a sub-agent when the surface is large.
-- **Planning is read-only.** Make no source edits while building or reviewing.
-  Start editing only after the user approves the UI direction.
-- **Clarify vs. assume.** Do not ask how to build the UI — present the direction
-  and options as mockups and tabs. Ask a clarifying question only when an
-  ambiguity would change the design; use the host agent's normal
-  ask-user-question flow and batch 2-4 before finalizing. Do not call
-  \`create-visual-questions\` from \`/ui-plan\`; keep answerable follow-up inside
-  the same plan as a bottom \`question-form\` Open Questions block. Otherwise
-  state the assumption in the plan and proceed.
-- **The plan is the approval gate.** Ask the user to review and approve the UI
-  direction before you write code, and name the files/areas the work touches.
-
-## UI-First Workflow
-
-1. Follow the host agent's normal planning flow: inspect the codebase, gather
-   the UI/component context needed, and ask native clarifying questions as needed
-   before generating the plan.
-2. Call \`create-ui-plan\` with a UI-specific title, brief, source, repo path, and
-   structured \`content\`. The canvas comes first, the document second.
-3. Compose the top canvas from the kit (see the cores below): the key artboards
-   with real product content, designer notes, and connectors only for real
-   sequences. Skip the canvas when wireframes would not clarify the work.
-4. Continue below as a concise technical document that stays close to the
-   Markdown plan the agent would normally output — not a second copy of the
-   canvas — covering concrete files, contracts, phases, risks, and validation.
-5. Call \`get-plan-feedback\` before implementation, after review, after a long
-   pause, and before the final response. Treat \`anchorDetails\`, resolver intent,
-   recent review events, and any focused screenshots from browser handoff as the
-   source of truth for exactly what changed and exactly what each UI comment
-   points at. Apply changes with \`update-visual-plan\`, preferring
-   \`contentPatches\` for one frame, annotation, node, tab, or block. When the
-   user wants source-control friendly edits, use \`patch-visual-plan-source\`
-   against the MDX files instead of regenerating the plan.
-
-## Agent Handoff
-
-After the canvas and document, add a short handoff that names the chosen UI
-direction, unresolved visual questions, and feedback that must be read before
-code changes. Never claim feedback has been applied until \`get-plan-feedback\` or
-the user has supplied it.
-
-## Wireframe & Canvas Core
-
-This section is shared by \`/visual-plan\` and \`/ui-plan\`, and is the single
-source of truth for how wireframes and the canvas work. The wireframe-quality
-rules below are additionally shared, word for word, with \`/visual-recap\`; the
-canvas/artboard mechanics apply only to \`/visual-plan\` and \`/ui-plan\`. Do not
-paraphrase any of it per command.
-
-${WIREFRAME_QUALITY_CORE}
-
-${CANVAS_SURFACE_CORE}
-
-## Document Quality Core
-
-This section is shared, word for word, by \`/visual-plan\` and \`/ui-plan\`. It is
-the single source of truth for the document below the canvas. Do not paraphrase
-it per command.
-
-${DOCUMENT_QUALITY_CORE}
-
-## Good vs. Bad Exemplar
-
-${EXEMPLAR_CORE}
-
-## Tool Guidance
-
-- \`create-ui-plan\`: create the UI-first structured visual plan.
-- \`create-prototype-plan\`: create a prototype-first plan when UI review needs a
-  functional live prototype.
-- \`create-plan-design\`: create a full-fidelity branded design plan when polish,
-  brand, and detailed visual direction are primary review inputs.
-- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
-  into a prototype plan.
-- \`create-visual-questions\`: use only for the explicit \`/visual-questions\`
-  command, not as \`/ui-plan\` preflight.
-- \`update-visual-plan\`: revise content, mockups, comments, or handoff notes;
-  prefer targeted \`contentPatches\`.
-- \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
-  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\`: inspect the current structured plan, exported HTML, and
-  annotations; it also returns the MDX folder for source workflows.
-- \`get-plan-feedback\`: read unconsumed reviewer comments before coding; it
-  returns grouped threads, exact anchor details, expected resolver, and recent
-  review-event payloads so agents can act only on the comments meant for them.
-- \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
-  files for repo check-in.
+## Visibility & Sharing
 
-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.
+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
 
@@ -1152,10 +1115,12 @@ intended), so the first tool call does not hit an OAuth wall:
 agent-native skills add visual-plan
 \`\`\`
 
-After that, \`/visual-plan\` (and \`/visual-recap\`, \`/ui-plan\`,
-\`/prototype-plan\`, \`/plan-design\`, \`/visual-questions\`) generate a plan and open
-the editor. Pass \`--no-connect\` to
-register the connector without authenticating, then run
+After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
+commands. Other planning modes — UI-first (\`create-ui-plan\`), prototype-first
+(\`create-prototype-plan\`), design-first (\`create-plan-design\`), and visual
+intake (\`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
 \`agent-native connect https://plan.agent-native.com\` whenever you are ready.
 
 **Browser (people you share with).** Open the Plans editor and create & edit
@@ -1178,273 +1143,6 @@ is available.
 Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
 not put shared secrets in skill files.
 `;
-export const PROTOTYPE_PLAN_SKILL_MD = `---
-name: prototype-plan
-description: >-
-  Use Agent-Native Plans for /prototype-plan when work needs a functional
-  prototype-first plan, static mocks, comments, review toggles, or conversion
-  from a visual plan.
-metadata:
-  visibility: exported
----
-
-# Prototype Plan
-
-\`/prototype-plan\` creates a plan whose primary review surface is a live,
-functional prototype above the document. Use it when the user needs to feel a
-flow, operate basic UI state, or comment on interaction before implementation
-hardens the decision.
-
-## Rule
-
-Make the prototype answer a concrete question. The plan should say what is being
-tested, show the functional prototype first, then keep static mocks and implementation
-notes in the document below.
-
-## When To Use
-
-Use \`/prototype-plan\` when the user asks for a prototype, wants to click through
-and operate UI states, needs design review before code, wants comments pinned to
-live screens, or asks to move a visual plan into a prototype.
-
-Prefer \`/visual-plan\` for architecture, data flow, or non-interactive planning.
-Prefer \`/ui-plan\` when static screen review is enough. Use \`/visual-plan\` first
-when the user hands you an existing Markdown/Codex/Claude plan that needs a
-visual companion before becoming interactive.
-
-## Core Workflow
-
-1. Inspect the real codebase and decide the question the prototype should
-   answer. Good examples: "Does this onboarding flow feel short enough?" or
-   "Which dashboard density should we implement?"
-2. Call \`create-prototype-plan\` with a title, brief, and screen HTML. Default to
-   one functional prototype screen when local UI behavior is enough; use 2-4
-   screens only for true routes, steps, or materially different contexts. The
-   returned plan opens with the prototype viewer on top and static mocks, flow
-   diagram, implementation map, and verification below.
-3. Make controls actually work. Use the renderer's safe Alpine-like directives:
-   \`x-data\`, \`x-model\`, \`x-for\`, \`x-text\`, \`x-show\`, \`:class\`, \`@click\`, and
-   \`@keydown.enter\`. Use safe helper verbs such as \`remove(list, item)\`,
-   \`setAll(list, 'done', true)\`, \`removeWhere(list, 'done', true)\`, and counters
-   such as \`count(list)\`, \`countWhere(list, 'done', true)\`, and
-   \`remaining(list, 'done')\` when they help. Use \`data-goto="screen-id"\` only
-   for true screen/route changes, not for every button press.
-4. Show important app feedback inside the prototype itself: selected filters,
-   checked rows, typed drafts, validation messages, permissions, progress, or
-   empty states.
-5. Surface the returned Plans link and ask the user to click through, comment on
-   the prototype or static mocks, and approve the direction before code changes.
-6. Before implementing or revising, call \`get-plan-feedback\`. Treat prototype
-   anchors, screenshots, and resolver intent as the source of truth.
-7. Update with \`update-visual-plan\` content patches. Use
-   \`patch-prototype-html\`, \`update-prototype-screen\`, or \`set-prototype\` for
-   targeted prototype edits instead of regenerating the whole plan.
-
-## Converting A Visual Plan
-
-When a visual plan already has HTML canvas wireframes, call
-\`convert-visual-plan-to-prototype\` with the plan id. This derives prototype
-screens from the canvas frames, preserves the canvas/static mocks by default,
-and changes the top review surface to the prototype viewer.
-
-Use \`removeCanvas: true\` only when the user explicitly wants the old canvas
-gone. Otherwise keep static mocks available for source export and detailed
-review.
-
-## Prototype Screen HTML
-
-Write bounded semantic HTML fragments only:
-
-\`\`\`html
-<div style="display:flex;flex-direction:column;gap:14px;padding:18px;height:100%">
-  <header style="display:flex;justify-content:space-between;gap:12px">
-    <div>
-      <h1>Launch checklist</h1>
-      <p class="wf-muted">Reviewer can add, complete, filter, and remove tasks.</p>
-    </div>
-    <span class="wf-pill accent">Live prototype</span>
-  </header>
-  <section
-    class="wf-card"
-    x-data="{ draft: '', filter: 'all', todos: [{ text: 'Check copy', done: false }, { text: 'Confirm owner', done: true }] }"
-    style="display:flex;flex-direction:column;gap:10px"
-  >
-    <div style="display:flex;gap:8px">
-      <input x-model="draft" @keydown.enter="draft && todos.push({ text: draft, done: false }); draft = ''" placeholder="Add task" />
-      <button class="primary" @click="draft && todos.push({ text: draft, done: false }); draft = ''">Add</button>
-    </div>
-    <div style="display:flex;gap:8px">
-      <button @click="filter = 'all'" :class="{ primary: filter === 'all' }">All</button>
-      <button @click="filter = 'done'" :class="{ primary: filter === 'done' }">Done</button>
-      <button @click="setAll(todos, 'done', true)">Mark all done</button>
-    </div>
-    <p class="wf-muted"><span x-text="remaining(todos, 'done')"></span> open / <span x-text="count(todos)"></span> total</p>
-    <div
-      class="wf-box"
-      x-for="todo in todos"
-      x-show="filter === 'all' || (filter === 'done' && todo.done)"
-      :class="{ 'is-done': todo.done }"
-      style="display:flex;justify-content:space-between;gap:10px"
-    >
-      <label style="display:flex;gap:8px"><input type="checkbox" x-model="todo.done" /><span x-text="todo.text"></span></label>
-      <button @click="remove(todos, todo)">Remove</button>
-    </div>
-    <button @click="removeWhere(todos, 'done', true)">Clear completed</button>
-  </section>
-</div>
-\`\`\`
-
-Use real labels, counts, dates, and controls grounded in the target app. Keep
-surfaces honest: \`browser\` for web pages, \`desktop\` for app shells, \`mobile\`
-only for real mobile work, \`panel\` for side panels, and \`popover\` for menus.
-
-Do not include \`<html>\`, \`<body>\`, \`<script>\`, \`<style>\`, browser \`on*\`
-handler attributes such as \`onclick\`, fake APIs, raw secrets, or customer data.
-The renderer owns sketchy/clean mode, theme, surface sizing, rough outlines, and
-comment overlays.
-
-## Review Surface
-
-Prototype plans support:
-
-- real local controls through safe prototype directives
-- optional screen/route transitions from \`data-goto\`
-- rough vs clean mode through the shared wireframe toggle
-- dark vs light mode through the shared theme toggle
-- comment visibility from the prototype toolbar
-- Figma-style comments pinned directly on live prototype screens
-- a popout URL with \`?prototype=1\` for focused browser review
-- static wireframe mocks in the document body where they help implementation
-
-## Source Files
-
-Runtime JSON is canonical. Source export uses:
-
-- \`plan.mdx\` for document blocks
-- \`prototype.mdx\` for \`<Prototype>\`, \`<PrototypeScreen>\`, and
-  \`<PrototypeTransition>\`
-- \`canvas.mdx\` for static mocks when a canvas is present
-- \`.plan-state.json\` for persisted viewport state
-
-Patch source with \`patch-visual-plan-source\` only when the user wants
-source-control friendly edits. Patch runtime content when the user is simply
-reviewing and iterating.
-
-## Related Skills
-
-- \`visual-plan\`
-- \`ui-plan\`
-- \`visual-questions\`
-`;
-export const PLAN_DESIGN_SKILL_MD = `---
-name: plan-design
-description: >-
-  Use Agent-Native Plans for full-fidelity UI design planning with a Design
-  canvas tab and optional interactive Prototype tab before implementation.
-metadata:
-  visibility: exported
----
-
-# Plan Design
-
-Use \`/plan-design\` when the user needs a high-fidelity product design before
-implementation: polished branded screens, realistic content, visual direction,
-and interaction review. It is the full-fidelity companion to \`/visual-plan\` and
-\`/prototype-plan\`: the top review surface should show \`Design\` and, when the
-flow needs interaction, \`Prototype\`.
-
-## When To Use
-
-Use this for UI-heavy work where brand, visual hierarchy, polished layout, or
-interaction feel are material to the decision. Skip it for small copy, spacing,
-or obvious component changes.
-
-## Research First
-
-Before creating the plan:
-
-1. Inspect the real app shell, routes, components, CSS variables, Tailwind
-   tokens, theme files, and any relevant screenshots.
-2. If \`design.md\` exists, treat it as the primary design brief and pass its
-   important content into \`create-plan-design.designMd\`.
-3. If a \`.fig\` local-copy file or parsed brand kit is available, use the
-   Design/brand-kit parsing actions from the app or shared tooling first, then
-   pass the extracted token summary into \`brandKit\`.
-4. Parse existing codebase style info when possible: CSS custom properties,
-   Tailwind config, global CSS, font declarations, spacing/radius tokens, and
-   component conventions. Pass the compact evidence into \`codebaseStyles\`.
-5. Ground every screen in actual product content. Avoid lorem ipsum, generic
-   marketing filler, and placeholder gray boxes unless designing an explicit
-   loading state.
-
-## Create The Plan
-
-Call \`create-plan-design\` with:
-
-- \`title\`, \`brief\`, \`repoPath\`, and any \`implementationNotes\`.
-- \`designMd\`, \`brandKit\`, \`codebaseStyles\`, or \`designNotes\` when available.
-- \`screens\`: one to six full-fidelity HTML/CSS screen fragments. Each screen
-  must include a bounded \`html\` fragment, optional scoped \`css\`, a \`surface\`,
-  and stable \`data-design-id\` attributes on elements a reviewer might edit.
-- \`transitions\` only when the Prototype tab should support true screen/step
-  navigation. Use \`data-goto="screen-id"\` in the screen HTML for those controls.
-
-The Design tab is the visual source of truth. The Prototype tab is for behavior
-and should reuse the same visual styling where practical. Do not create a
-separate design direction in the prototype.
-
-## Full-Fidelity HTML Rules
-
-- Write bounded fragments only: no \`<html>\`, \`<head>\`, \`<body>\`, \`<script>\`,
-  \`<style>\`, external imports, iframes, SVG, or executable URLs.
-- Put CSS in the screen \`css\` field. The renderer scopes it to the artboard.
-- Use real CSS and CSS variables. Tailwind-like class names are fine only when
-  the provided \`css\` defines them or the classes are harmless semantic hooks.
-- Use \`renderMode: "design"\` on design screen data when authoring full
-  structured content directly.
-- Add \`data-design-id="meaningful-name"\` to editable elements such as hero
-  panels, key buttons, cards, nav items, pricing rows, chart panels, and state
-  chips. Keep ids stable and descriptive.
-- Keep the design responsive within the selected surface. Text must not clip,
-  overlap, or rely on viewport-sized type.
-
-## Targeted Style Edits
-
-When a reviewer selects an element in the Design tab or asks for a specific
-style change, avoid regenerating the whole plan. Use:
-
-\`\`\`json
-{
-  "op": "update-design-element-style",
-  "frameId": "frame-overview",
-  "elementId": "primary-cta",
-  "styles": {
-    "background-color": "#0f766e",
-    "border-radius": "10px"
-  }
-}
-\`\`\`
-
-Use \`frameId\` for inline canvas designs or \`blockId\` for a referenced wireframe
-block. Set a style value to \`null\` to remove it. Use \`patch-wireframe-html\` or
-\`patch-prototype-html\` for text/content changes inside a fragment.
-
-## Document Handoff
-
-Below the visual surface, keep the document concise and implementation-oriented:
-actual files and symbols, state/actions/contracts, open questions, risks, and
-verification. The document should not repeat the same screens in prose.
-
-Before implementation, call \`get-plan-feedback\` and treat comments, selected
-element details, and recent review events as the source of truth.
-
-## Related Skills
-
-- \`visual-plan\`
-- \`ui-plan\`
-- \`prototype-plan\`
-- \`frontend-design\`
-`;
 export const VISUAL_RECAP_SKILL_MD = `---
 name: visual-recap
 description: >-
@@ -1466,25 +1164,64 @@ 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 app, 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 \`agent-native 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.
+- Write the recap as a local MDX folder under \`plans/<slug>/\`: \`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.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind recap\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- 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.
+- Treat review feedback as file or chat feedback: update the MDX files directly,
+  rerun the local preview command, and summarize the new local URL/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 server. 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.
-
-If the \`plan\` MCP server's tools are not available, do NOT improvise an inline
-recap as a fallback. 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: reconnect the plan MCP server (in Claude Code, run \`/mcp\` and
-reconnect, or restart the session); only if it is genuinely unauthenticated, run
-\`agent-native connect <plan-app-url>\` or re-authenticate via \`/mcp\`. Then publish
-once the tool is reachable. Falling back to inline content is a defect, not a
-degraded mode.
+\`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.
+
+Except for the explicit local-files privacy mode above, if neither the \`plan\`
+nor legacy \`agent-native-plans\` Plan MCP tools are available, 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\`. 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: reconnect the Plan MCP connector (in
+Claude Code, run \`/mcp\` and reconnect, or restart the session); only if it is
+genuinely unauthenticated, run \`agent-native connect <plan-app-url>\` or
+re-authenticate via \`/mcp\`. Then publish once the tool is reachable. Falling
+back to inline content is a defect, not a degraded mode.
 
 ## When To Use
 
@@ -1535,282 +1272,87 @@ 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 \`diff\` of the KEY changed files, grouped under a \`## Key changes\`
-  \`rich-text\` heading in a single vertical \`tabs\` block (file labels as the left
-  rail), 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. Leave \`mode\` unset so each diff renders unified — the default — because a
-  tab panel is too narrow for split's side-by-side gutters to stay legible.
-
-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.
-
-## UI Impact Needs Wireframes
-
-When the diff changes rendered UI, layout, density, visual state, interaction
-affordances, navigation, controls, menus, dialogs, or design tokens, the recap
-MUST include one or more wireframes. Prose and file diffs are not a substitute
-for showing what changed visually.
-
-Choose the smallest visual surface that makes the review clear:
-
-- Use a \`Before\` / \`After\` wireframe pair when the reviewer benefits from direct
-  comparison, such as a removed or added control, a changed state, layout
-  density, ordering, navigation, or a visible component replacement. The
-  Wireframe Quality core below owns how to lay that pair out (columns vs.
-  vertical stack by geometry).
-- Use an after-only wireframe when the change is purely additive or the "before"
-  state would only show absence without adding review value.
-- Use more than two wireframes when the UI change is flow-dependent, responsive,
-  or stateful; show the meaningful states in order instead of forcing a single
-  before/after pair.
-- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
-  matching \`surface\` (\`popover\`, \`panel\`, etc.) and show the focused sub-surface.
-  Do not redraw a full page unless placement in the page is itself part of the
-  change.
-
-Ground each wireframe in the changed UI behavior, component names, file paths,
-and diff-visible labels/states. If exact pixels are inferred rather than
-captured, say so in the wireframe caption or a concise annotation. For
-local/manual recaps, import or update the plan source that holds the wireframes
-so the rendered recap opens with the UI visual available.
-
-## Wireframe Quality
-
-UI recap wireframes must look like the UI surface that changed, not like generic
-architecture boxes. The following bar is shared, word for word, with
-\`/visual-plan\` and \`/ui-plan\`: it is the single source of truth for HTML
-wireframe quality, and applies to a recap's standalone \`wireframe\` /
-\`WireframeBlock\` / \`<Screen>\` exactly as it applies to a plan's canvas artboard.
-
-<!-- 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, font-family, hex colors,
-or any width/height/coordinates. You write real HTML layout and real product
-content; the renderer styles and roughens it.
-
-**A wireframe block's data is an HTML screen plus a surface:**
-
-\`\`\`json
-{
-  "surface": "browser",
-  "html": "<div style=\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\"><h1>Sign in</h1><p class=\\"wf-muted\\">Use your work email to continue.</p><div class=\\"wf-card\\" style=\\"display:flex;flex-direction:column;gap:10px\\"><label>Email<input value=\\"jane@acme.co\\" /></label><label>Password<input value=\\"••••••••\\" /></label><label style=\\"display:flex;align-items:center;gap:8px\\"><input type=\\"checkbox\\" checked /> Remember me</label><button class=\\"primary\\">Sign in</button></div><a href=\\"#\\">Forgot password?</a></div>"
-}
-\`\`\`
-
-**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
-(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
-are auto-themed — no classes needed. Helper classes carry the rest:
-
-- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
-- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
-  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
-- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
-- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
-  primary button.
-
-**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
-these on light/dark, so reading them is what keeps a mockup correct in both
-themes. For any inline border, background, or text color, reference a token:
-\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
-\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
-(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
-\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
-and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
-renderer owns the sketch/clean font.
-
-**Lay out with inline \`style\` flex/grid.** You write the real layout —
-\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
-renderer never repositions anything. Compose the actual product: reproduce the
-current screen, then show the modification. Real labels, real counts, real dates,
-real button text grounded in the screen you read; not lorem or gray bars.
-
-**Surface presets — match the real footprint, never default to desktop+mobile.**
-Pick the \`surface\` that matches what the user will actually see:
-
-- \`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.
-
-**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.** 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.
-
-**Treat the wireframe border as part of the visible design.** Always wrap HTML
-wireframe content in a root container with real inner padding before drawing
-cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows so the
-first row never sits flush against the screen border. Keep text away from
-borders: every container, field, button, menu item, and annotation needs enough
-padding and line-height to read cleanly in the rendered Plan view.
-
-**Lay out children safely so they never collide.** Use HTML flex/grid with
-\`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute
-positioning, or fixed child widths that can collide when the renderer switches
-between light/dark, sketch/clean, or different zoom levels.
-
-**Do not wrap intentionally single-line labels.** For 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.** 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.
-
-**Let the surface choose side-by-side vs. stacked.** 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>
-\`\`\`
+  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.
+
+## 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. The
+  Wireframe Quality core below owns how to lay that pair out (columns vs.
+  vertical stack by geometry).
+- Use an after-only wireframe when the change is purely additive or the "before"
+  state would only show absence without adding review value.
+- Use more than two wireframes when the UI change is flow-dependent, responsive,
+  or stateful; show the meaningful states in order instead of forcing a single
+  before/after pair.
+- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
+  matching \`surface\` (\`popover\`, \`panel\`, etc.) and show the focused sub-surface.
+  Do not redraw a full page unless placement in the page is itself part of the
+  change.
+
+Ground each wireframe in the changed UI behavior, component names, file paths,
+and diff-visible labels/states. If exact pixels are inferred rather than
+captured, say so in the wireframe caption or a concise annotation. For
+local/manual recaps, import or update the plan source that holds the wireframes
+so the rendered recap opens with the UI visual available.
 
-<!-- SHARED-CORE:wireframe-quality END -->
+## 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; kit-tree wireframes are appropriate for simpler layouts. For HTML
+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.
@@ -1822,6 +1364,11 @@ text-match screenshot is not enough; visually inspect the captured image.
 
 ## Open And Report The Recap
 
+In local-files privacy mode, report the local preview URL/path from
+\`agent-native plan local preview\` or the \`/local-plans/<slug>\` route for a local
+Plan app using the same \`PLAN_LOCAL_DIR\`. Do not invent a hosted 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
@@ -1865,7 +1412,9 @@ 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 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
@@ -1892,42 +1441,36 @@ the actual diff:
 - **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 \`diff\` for the literal lines.
-- **Any meaningful code hunk** → \`diff\` carrying the real \`before\` / \`after\` text
-  and the \`filename\` / \`language\`. Leave \`mode\` unset: unified is the default and
-  the right choice for a recap, since recap diffs almost always sit inside a
-  width-constrained container (a vertical-tabs panel or a comparison column)
-  where split's two line-number gutters cut the code off. Reach for \`mode:
-  "split"\` only for a standalone, full-document-width diff where side-by-side
-  genuinely helps. 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.
+  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 is
-  \`{ side?: "before" | "after"; lines: "13" | "13-15"; label?: string; note }\`
-  and 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.
+  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
-  \`orientation: "vertical"\` so file labels form a left rail and the selected
-  file's diff renders unified on the right. Leave each diff's \`mode\` unset — the
-  tab panel is too narrow for split — and let the unified default carry it. 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.
+  \`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.
   If the recap ends with more than one supporting diff, that trailing diff
-  appendix should be one vertical \`tabs\` block under its own \`## Key changes\`
+  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 \`diff\`. Carry the real new code
+  \`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 (\`{ lines: "12" | "12-18"; label?; note }\`) so the reviewer reads
-  what the new code does, not code for code's sake. Keep \`diff\` for true
-  before/after hunks where the removed lines still carry meaning, and group
-  several annotated walkthroughs in a vertical \`tabs\` block the same way diffs are
-  grouped.
+  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.
@@ -1936,15 +1479,17 @@ the actual diff:
   wireframes when the comparison clarifies the change; otherwise use after-only
   or a short state/flow sequence. Use realistic UI surfaces: for a popover
   change, show a popover with its title row, top-right actions, options/fields,
-  and any opened prompt/menu anchored to the correct trigger. Keep the body lean:
-  the wireframe carries the UI story, while the file tree and \`diff\`
-  blocks carry implementation evidence.
+  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 the two-dimensional layouts the Document Quality core
-  prescribes; do not reduce a structural change to a left-to-right chain.
-  Do not use \`diagram\` as a stand-in for rendered UI controls; UI changes need
-  \`wireframe\` blocks.
+  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.
   Diagram HTML/CSS should use renderer-owned primitives such as
   \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
   \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; these map to the plan's
@@ -1957,349 +1502,56 @@ the actual diff:
   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 MDX reference
-
-This is the authoritative tag + prop shape for every importable block. Author the
-recap source against THESE tags and props — do not guess from the conceptual
-names above (the conceptual name like \`api-endpoint\` is NOT the JSX tag). A wrong
-tag or prop shape either 500s the import with a ZodError or, for an unrecognized
-capitalized tag, now **fails the import with a clear "Unknown plan block" error**
-(it used to silently render as raw \`<JsonExplorer …>\` text — that footgun is
-fixed). Every block also takes the shared envelope attributes \`id\` (REQUIRED,
-unique across the whole plan), and optional \`title\`, \`summary\`, \`editable\` —
-those are omitted from the per-block prop lists below.
-
-The complete set of real block tags is exactly: \`RichText\`, \`FileTree\`,
-\`DataModel\`, \`Endpoint\`, \`Diff\`, \`AnnotatedCode\`, \`WireframeBlock\` (body
-\`<Screen>\` + wireframe-kit children), \`Columns\`/\`Column\`, \`TabsBlock\`, \`Callout\`,
-\`Diagram\`, \`Mermaid\`, \`Json\`, \`HtmlBlock\`, \`Table\`, \`Checklist\`, \`Code\`,
-\`OpenApi\`. Any other capitalized tag at the block level is rejected on import.
-
-Quick tag map (conceptual name → real JSX tag):
-
-| Conceptual | Real tag | Conceptual | Real tag |
-| --- | --- | --- | --- |
-| api-endpoint | \`Endpoint\` | diff | \`Diff\` |
-| data-model | \`DataModel\` | annotated-code | \`AnnotatedCode\` |
-| file-tree | \`FileTree\` | code | \`Code\` |
-| mermaid | \`Mermaid\` | rich-text | \`RichText\` |
-| diagram | \`Diagram\` | callout | \`Callout\` |
-| json-explorer | \`Json\` | columns | \`Columns\` (cols are \`Column\`) |
-| openapi-spec | \`OpenApi\` | tabs | \`TabsBlock\` |
-| wireframe | \`WireframeBlock\` (body \`<Screen>\`) | table | \`Table\` |
-| custom-html | \`HtmlBlock\` | checklist | \`Checklist\` |
-
-### Common mistakes (these now error on import)
-
-These WRONG tags used to be swallowed as raw text. Common synonyms are now
-auto-corrected to the canonical tag on import; anything not in this map is
-rejected with a "did you mean" hint. Always author with the canonical tag —
-do not rely on the aliases.
-
-| WRONG tag | → use |
-| --- | --- |
-| \`JsonExplorer\` | \`Json\` |
-| \`Tabs\` (or a nested \`Tab\` child) | \`TabsBlock\` (tabs are ONE JSON \`tabs={[…]}\` prop — there is NO nested \`<Tab>\` element) |
-| \`ApiEndpoint\` | \`Endpoint\` |
-| \`DiffBlock\` | \`Diff\` |
-| \`AnnotatedCodeBlock\` | \`AnnotatedCode\` |
-| \`Wireframe\` | \`WireframeBlock\` |
-
-Lowercase HTML tags inside \`RichText\`/markdown prose (\`<div>\`, \`<span>\`,
-\`<code>\`, \`<br>\`, …) are always fine — only capitalized component-style tags at
-the block level are validated.
-
-### \`Endpoint\` (API / route)
-
-Tag is \`Endpoint\` — NOT \`ApiEndpoint\`. Required attrs: \`method\`, \`path\`. Optional
-attrs: \`summary\` (the short title — NOT \`title\`), \`auth\`, \`deprecated\` (bool),
-\`change\`, \`params\`, \`request\`, \`responses\`. The prose \`description\` is the MDX
-**children** (body between the tags), NOT an attribute.
-
-- \`method\` ∈ \`GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS\`. For a
-  WebSocket upgrade use \`GET\`.
-- \`change\` (and per-param/per-response \`change\`) ∈ \`added | modified | removed | renamed\`.
-- \`params={[{ name, in, type?, required?, description?, change?, was? }]}\` where
-  \`in\` ∈ \`path | query | header | body\`.
-- \`request={{ contentType?, example? }}\` — \`example\` is a JSON **string**, not a
-  nested object.
-- \`responses={[{ status, description?, example?, change? }]}\` — each \`example\` is
-  a JSON **string** (the renderer parses it into the collapsible JsonExplorer).
-  Give each distinct message shape (e.g. success vs error, or separate WS frame
-  types) its OWN response entry, not one merged body.
-
-\`\`\`mdx
-<Endpoint
-  id="ep-create-task"
-  method="POST"
-  path="/api/tasks"
-  summary="Create a task"
-  request={{ contentType: "application/json", example: '{"title":"Ship recap"}' }}
-  responses={[{ status: "201", description: "Created", example: '{"id":"t_1","title":"Ship recap"}' }]}
->
-
-Creates a task scoped to the caller's org.
-
-</Endpoint>
-\`\`\`
-
-### \`DataModel\` (schema / ER)
-
-Tag is \`DataModel\`. Required attr: \`entities\` (>= 1). Optional attr: \`relations\`.
-There is NO top-level \`fields=\` attribute — fields live inside each entity. There
-is NO per-field \`required\` or \`description\` key; fold either into \`note\`.
-
-- \`entities={[{ id, name, note?, change?, fields: [...] }]}\` — \`id\` is referenced
-  by relations.
-- each field: \`{ name, type?, pk?, fk?, nullable?, default?, note?, change?, was? }\`.
-  \`pk\`/\`nullable\` are booleans; \`fk\` is a string target like \`"User.id"\`;
-  \`change\` ∈ \`added | modified | removed | renamed\`; \`was\` is the prior value
-  when \`change\` is \`modified\`.
-- \`relations={[{ from, to, kind?, label? }]}\` (optional — the renderer infers
-  simple \`1-n\` from \`fk\` when omitted); \`kind\` ∈ \`1-1 | 1-n | n-n\`.
-
-\`\`\`mdx
-<DataModel
-  id="dm-tasks"
-  entities={[
-    {
-      id: "task",
-      name: "Task",
-      fields: [
-        { name: "id", type: "uuid", pk: true },
-        { name: "title", type: "text" },
-        { name: "status", type: "text", change: "added", note: "open|done" }
-      ]
-    }
-  ]}
-/>
-\`\`\`
-
-### \`FileTree\` (changed files)
-
-Tag is \`FileTree\`. Required attr: \`entries\` (>= 1). Optional attr: \`title\`. The
-tree is built from the leaf \`path\`s — do NOT pass an ASCII tree in children; the
-block is self-closing.
-
-- \`entries={[{ path, change?, note?, snippet?, language? }]}\` — \`path\` is
-  slash-delimited; \`change\` ∈ \`added | modified | removed | renamed\`. Add a
-  \`snippet\` (with optional \`language\`) only when it says something the path does
-  not.
-
-\`\`\`mdx
-<FileTree
-  id="ft-changed"
-  title="Files touched"
-  entries={[
-    { path: "server/routes/tasks.ts", change: "modified", note: "add POST handler" },
-    { path: "server/db/schema.ts", change: "modified" },
-    { path: "tests/tasks.test.ts", change: "added" }
-  ]}
-/>
-\`\`\`
-
-### \`Mermaid\` (graph)
-
-Tag is \`Mermaid\` — this is its OWN block, separate from \`Diagram\`. Required attr:
-\`source\` (the diagram text). Optional attr: \`caption\`. Do NOT put mermaid text
-inside a \`Diagram\` block, and do NOT use \`<Diagram mermaid={...}>\` — that is not a
-real prop and will not render.
-
-\`\`\`mdx
-<Mermaid
-  id="mm-flow"
-  source={\`flowchart LR
-  Client --> API
-  API --> DB\`}
-  caption="Request path"
-/>
-\`\`\`
-
-### \`Diagram\` (HTML/SVG or node graph)
-
-Tag is \`Diagram\`. The whole payload is ONE \`data\` attribute:
-\`data={{ html?, css?, caption?, nodes?, edges?, notes? }}\`. It requires either
-\`html\` (an inert HTML/SVG fragment) OR at least one node — a \`Diagram\` with
-neither fails validation. This is for architecture / data-flow / dependency
-relationships, NOT rendered UI (use a wireframe for UI) and NOT mermaid (use
-\`Mermaid\`). Use \`.diagram-*\` primitives + \`--wf-*\` tokens in \`html\`/\`css\`; never
-hex colors or \`font-family\`.
-
-\`\`\`mdx
-<Diagram
-  id="dg-arch"
-  data={{
-    nodes: [
-      { id: "ui", label: "UI" },
-      { id: "api", label: "API" },
-      { id: "db", label: "DB" }
-    ],
-    edges: [
-      { from: "ui", to: "api" },
-      { from: "api", to: "db" }
-    ]
-  }}
-/>
-\`\`\`
-
-### \`Json\` (JSON explorer)
-
-Tag is \`Json\`. Required attr: \`json\` — a **string** containing the JSON.
-Optional attrs: \`title\`, \`collapsedDepth\` (number, default 2).
-
-\`\`\`mdx
-<Json
-  id="json-config"
-  title="Resolved config"
-  json={'{"flags":{"recap":true},"limit":50}'}
-/>
-\`\`\`
-
-### \`Diff\` (before/after)
-
-Tag is \`Diff\`. Required attrs: \`before\`, \`after\` (multiline source strings).
-Optional attrs: \`filename\`, \`language\`, \`mode\` (\`unified | split\`), \`annotations\`.
-Leave \`mode\` unset: it defaults to **unified**, which reads cleanly at any width
-and is what recap diffs want — they almost always live inside a width-constrained
-container (a vertical-tabs panel or a comparison column) where split's two
-line-number gutters cut the code off. Only set \`mode: "split"\` for a standalone,
-full-document-width diff where side-by-side genuinely helps. The reader always
-exposes a Unified/Split toggle (when there is room), so a viewer can switch
-either way regardless of the authored default. Give every diff a \`summary\` (the
-shared envelope attr) so the reviewer reads intent first.
-
-- \`annotations={[{ side?, lines, label?, note }]}\` — \`side\` ∈ \`before | after\`
-  (default \`after\`); \`lines\` is a 1-based ref like \`"13"\` or \`"13-15"\`.
-
-\`\`\`mdx
-<Diff
-  id="diff-handler"
-  filename="server/routes/tasks.ts"
-  language="ts"
-  summary="Add the POST /api/tasks handler"
-  before={\`router.get("/api/tasks", list);\`}
-  after={\`router.get("/api/tasks", list);\\nrouter.post("/api/tasks", create);\`}
-  annotations={[{ side: "after", lines: "2", label: "New route", note: "Creates a task" }]}
-/>
-\`\`\`
-
-### \`AnnotatedCode\` (new-file walkthrough)
-
-Tag is \`AnnotatedCode\`. Required attr: \`code\` (multiline string). Optional attrs:
-\`filename\`, \`language\`, \`annotations\`. Use this for a brand-new file with no
-meaningful "before".
-
-- \`annotations={[{ lines, label?, note }]}\` — 1-based \`lines\` ref (no \`side\`,
-  unlike \`Diff\`).
-
-\`\`\`mdx
-<AnnotatedCode
-  id="ac-create"
-  filename="server/tasks/create.ts"
-  language="ts"
-  code={\`export async function create(input: NewTask) {\\n  return db.tasks.insert(input);\\n}\`}
-  annotations={[{ lines: "1-3", label: "Handler", note: "Inserts and returns the row" }]}
-/>
-\`\`\`
-
-### \`RichText\` (prose)
-
-Tag is \`RichText\`. The markdown is the MDX **children** (body between the tags),
-NOT an attribute. Use \`## Key changes\` here as the heading above a grouped diff
-\`TabsBlock\`.
-
-\`\`\`mdx
-<RichText id="rt-why">
-
-## Why
-
-Adds a create endpoint so the agent can author tasks directly.
-
-</RichText>
-\`\`\`
-
-### \`Callout\` (tone note)
-
-Tag is \`Callout\`. Optional attr: \`tone\` ∈ \`info | decision | risk | warning | success\`.
-The body markdown is the MDX **children**, NOT an attribute.
-
-\`\`\`mdx
-<Callout id="co-risk" tone="risk">
-
-The new column is non-nullable with no default — existing rows need a backfill.
-
-</Callout>
-\`\`\`
-
-### \`Columns\` (side-by-side)
-
-Tag is \`Columns\`; each column is a nested \`<Column label="...">\` whose body is
-markdown and/or block components. 1–4 columns. Use labels \`Before\` / \`After\` for
-structured comparisons.
-
-\`\`\`mdx
-<Columns id="cols-schema">
-<Column label="Before">
-
-\`status\` did not exist.
-
-</Column>
-<Column label="After">
-
-<DataModel id="dm-after" entities={[{ id: "task", name: "Task", fields: [{ name: "status", type: "text", change: "added" }] }]} />
-
-</Column>
-</Columns>
-\`\`\`
-
-### \`TabsBlock\` (tab rail)
-
-Tag is \`TabsBlock\` — NOT \`Tabs\`, and there is NO nested \`<Tab>\` element. Required
-attr: \`tabs\` (1–12). Optional attr: \`orientation\` (\`horizontal | vertical\`; use
-\`vertical\` for a file rail). The whole \`tabs\` array (including nested child
-blocks) is ONE JSON prop; do NOT nest the tabs or their child blocks as MDX
-elements. Label the section with a preceding \`## Key changes\` \`RichText\` heading
-rather than a \`title\` on the block.
-
-\`\`\`mdx
-<TabsBlock
-  id="tabs-key"
-  orientation="vertical"
-  tabs={[
-    { id: "t-route", label: "routes/tasks.ts", blocks: [ /* Diff block objects */ ] },
-    { id: "t-schema", label: "db/schema.ts", blocks: [ /* Diff block objects */ ] }
-  ]}
-/>
-\`\`\`
-
-### \`WireframeBlock\` + \`<Screen>\` (UI)
-
-Tag is \`WireframeBlock\`; its body is a single \`<Screen surface ... >\` subtree
-(this is nested MDX, not a flat prop). On \`<Screen>\`, \`html\` must be a
-single-quoted string or a static template literal — NEVER a dynamic expression
-(\`html={someVar}\` throws on import). \`surface\` ∈
-\`desktop | mobile | popover | panel | browser\`. Optional \`<Screen>\` attrs:
-\`renderMode\` (\`wireframe | design\`), \`caption\`, \`css\`, \`skeleton\`. See the
-Wireframe Quality core above for the HTML rules.
-
-\`\`\`mdx
-<WireframeBlock id="wf-tasks">
-<Screen surface="browser" html={'<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"><h1>Tasks</h1><button class="primary">New task</button></div>'} />
-</WireframeBlock>
-\`\`\`
-
-### Other blocks
-
-- \`HtmlBlock\` (custom-html) — flat attrs \`html\` (required, bounded fragment),
-  \`css?\`, \`caption?\`. Prefer a wireframe for UI; this is an escape hatch.
-- \`Table\` — flat attrs \`columns={["A","B"]}\` and \`rows={[["1","2"]]}\` (both arrays
-  of strings), optional \`density\` (\`compact | normal | relaxed\`).
-- \`Checklist\` — flat attr \`items={[{ id, label, checked?, note? }]}\`.
-- \`Code\` — flat attrs \`code\` (required string), \`language?\`, \`filename?\`,
-  \`caption?\`, \`maxLines?\`. For a multi-file rail use a \`TabsBlock\` of \`Code\`
-  blocks.
-- \`OpenApi\` — flat attrs \`spec\` (required JSON string of a whole OpenAPI/Swagger
-  doc), \`title?\`. The whole-document counterpart to \`Endpoint\`.
+## 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, call \`get-plan-blocks\` on the Plan
+MCP connector (\`plan\` or legacy \`agent-native-plans\`).** It 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 block takes a REQUIRED \`id\` (unique across the whole plan) plus the
+  shared optional \`summary\` / \`editable\` envelope; give a block a heading by
+  placing a \`rich-text\` block with a Markdown \`###\` heading directly above it
+  (blocks no longer take a \`title\`).
+- \`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 the
+  Wireframe Quality core above 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
 
@@ -2313,16 +1565,19 @@ comparisons there are two primitives, and they cover the whole need together:
   "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. Leave \`mode\` unset so it renders unified (the default,
-  legible at any width); reserve \`mode: "split"\` for a standalone full-width diff
-  where side-by-side genuinely helps — never inside a tabs panel or column, where
-  split's doubled gutters cut the code off.
+  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. The Wireframe Quality core owns the before/after layout choice —
+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. The Wireframe Quality core 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
@@ -2356,15 +1611,19 @@ inferred (not extracted) as inferred in prose.
   hardcoded-secret rule: obviously fake placeholders only, never the real value,
   in any block, caption, or note.
 
-## Bidirectional Loop (Fast-Follow)
+## Bidirectional Loop
 
 Because a recap is a real, editable plan, the same review loop as forward plans
 applies: a reviewer can annotate any block, and the coding agent reads
 \`get-plan-feedback\` to drive fixes back into the code — annotation → agent →
-diff, the same close-the-loop flow forward plans use. In v1, recaps are
-**read-only**: they summarize a merged or proposed change for review, and the
-annotate-to-fix loop is a fast-follow, not yet wired. Build the recap so the
-blocks are anchorable and the loop drops in later without restructuring.
+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. 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
 
@@ -2375,143 +1634,6 @@ blocks are anchorable and the loop drops in later without restructuring.
   recap's redaction and visibility gating mirror.
 - **sharing** — org/login-gated visibility for the plan that holds the recap.
 `;
-export const VISUAL_QUESTIONS_SKILL_MD = `---
-name: visual-questions
-description: >-
-  Use Agent-Native Plans to ask rich visual intake questions when
-  /visual-questions is explicitly requested before creating a UI plan or visual
-  plan.
-metadata:
-  visibility: both
----
-
-# Visual Questions
-
-Use \`/visual-questions\` when the next best step is not a plan yet, but a
-reviewable visual intake: single-choice option rows, multi-select option rows,
-freeform notes, mockup choices, sketch diagrams, and a generated answer summary
-that feeds the next planning prompt. It composes with \`/visual-plan\`, \`/ui-plan\`,
-\`/prototype-plan\`, and \`/plan-design\`.
-
-## When To Use
-
-- The user asks to be shown options before the agent writes a plan.
-- UI direction, form factor, layout model, feature set, or visual style is fuzzy
-  enough that 2-6 answers would materially change the plan.
-- The user would benefit from choosing between visual mockups or diagrams rather
-  than answering text-only prompts.
-
-Gate hard: skip this for tiny, unambiguous changes. If the agent can reasonably
-infer the answer, prefer \`/ui-plan\`, \`/prototype-plan\`, \`/plan-design\`, or
-\`/visual-plan\` directly and put assumptions in the plan.
-
-Visual questions are an explicit intake command, not an automatic preflight for
-\`/visual-plan\`, \`/ui-plan\`, \`/prototype-plan\`, or \`/plan-design\`.
-
-## Workflow
-
-1. Call \`create-visual-questions\` with a clear title, brief, source, and repo
-   path when known.
-2. Omit \`questions\` for the default UI intake. Provide a custom \`questions\` array
-   only when the task has domain-specific choices.
-3. Surface the returned Plans link and ask the user to answer visually.
-4. The generated summary drives the next step: \`create-ui-plan\` for static UI
-   review, \`create-prototype-plan\` for click-through UI flows,
-   \`create-plan-design\` for high-fidelity branded UI review,
-   \`create-visual-plan\` for general plans or when a text plan already exists,
-   or \`update-visual-plan\` with targeted \`contentPatches\` to fold answers into
-   an active plan.
-5. If the user leaves comments, call \`get-plan-feedback\` before using the answers.
-
-## Question Types
-
-Supported \`questions\` entries:
-
-- \`single\`: chip group where one option wins.
-- \`multi\`: chip group where multiple options can be selected.
-- \`freeform\`: textarea for constraints, inspirations, or things to avoid.
-- \`visual\`: visual options with sketch previews — use for layout direction, flow
-  depth, surface choice, or diagram choices.
-
-Each option can include \`label\`, \`value\`, \`description\`, \`recommended\`,
-\`preview\`, and \`bullets\`. Valid \`preview\` values match the wireframe surfaces:
-\`desktop\`, \`mobile\`, \`popover\`, \`panel\`, \`component\`, \`split\`, \`flow\`, and
-\`diagram\`. Pick the preview that matches the real footprint — do not offer a
-desktop/mobile pair for a popover, panel, or component.
-
-\`single\`, \`multi\`, and \`visual\` questions always render a write-in field, so a
-reviewer can answer with their own option instead of the listed choices. Do not
-add an explicit "Other" or "Something else" option yourself; set
-\`allowOther: false\` only on the rare question where a free-text answer makes no
-sense.
-
-## Quality Bar
-
-- Ask only decision-changing questions. A beautiful form with low-value questions
-  is still friction.
-- Prefer visible, answerable options over abstract prose.
-- Use visual tabs when users need to compare layout or flow shapes.
-- Keep the output calm and document-like, not a landing page.
-- The generated answer summary is not the final plan; it is the intake prompt for
-  the next agent step.
-
-## Tool Guidance
-
-- \`create-visual-questions\`: create the interactive intake plan.
-- \`get-visual-plan\`: inspect the current visual question plan.
-- \`get-plan-feedback\`: read comments before creating or updating the next plan.
-- \`create-ui-plan\`: create a UI-first plan from the answers.
-- \`create-prototype-plan\`: create a prototype-first plan from the answers when
-  interaction feel matters.
-- \`create-plan-design\`: create a high-fidelity branded design plan from the
-  answers when visual polish is the primary review input.
-- \`create-visual-plan\`: create a general visual plan from the answers, or pass
-  existing plan text as \`planText\` when the answers should shape an imported
-  plan.
-- \`export-visual-plan\`: export answer plans as HTML, Markdown fallback,
-  structured JSON, and MDX files when the intake needs to be checked into a repo.
-- \`read-visual-plan-source\` / \`patch-visual-plan-source\`: inspect or patch the
-  MDX source if another agent is operating from checked-in plan files.
-
-## Setup & Authentication
-
-There are two ways into Plans.
-
-**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
-installs the Plans skills, registers the hosted Plans MCP connector, and
-authenticates it in the same step (a one-time browser sign-in at setup — this is
-intended), so the first tool call does not hit an OAuth wall:
-
-\`\`\`bash
-agent-native skills add visual-plan
-\`\`\`
-
-After that, \`/visual-plan\` (and \`/visual-recap\`, \`/ui-plan\`,
-\`/prototype-plan\`, \`/plan-design\`, \`/visual-questions\`) generate a plan and open
-the editor. Pass \`--no-connect\` to
-register the connector without authenticating, then run
-\`agent-native connect https://plan.agent-native.com\` whenever you are ready.
-
-**Browser (people you share with).** Open the Plans editor and create & edit
-with no sign-up — you work as a guest. Sign in only when you want to save or
-share; signing in claims the plans you made as a guest into your account.
-
-Sharing and commenting require an account: public/shared plans are viewable by
-anyone with the link, but commenting on them needs an agent-native account.
-
-For fully offline, no-account use, run the Plans app locally and sync plans to
-your repo as MDX. This local mode is a separate advanced path, not the default
-hosted flow.
-
-If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. Authenticate the connector with
-\`agent-native connect https://plan.agent-native.com\` (OAuth-capable hosts can
-instead re-run /mcp and choose Authenticate), then continue once the connector
-is available.
-
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
-not put shared secrets in skill files.
-`;
 export const BUILT_IN_APP_SKILLS = {
     assets: {
         skillName: "assets",
@@ -2603,10 +1725,19 @@ export const BUILT_IN_APP_SKILLS = {
         skillName: "visual-plan",
         extraSkills: {
             "visual-recap": VISUAL_RECAP_SKILL_MD,
-            "visual-questions": VISUAL_QUESTIONS_SKILL_MD,
-            "ui-plan": UI_PLAN_SKILL_MD,
-            "prototype-plan": PROTOTYPE_PLAN_SKILL_MD,
-            "plan-design": PLAN_DESIGN_SKILL_MD,
+        },
+        // Sibling reference files materialized alongside each skill's SKILL.md
+        // (progressive disclosure). Keyed by skill name -> relative path -> content.
+        // Both plan skills ship the same canonical wireframe-quality reference; the
+        // canvas / document-quality / exemplar references are visual-plan only.
+        extraFiles: {
+            "visual-plan": {
+                "references/wireframe.md": WIREFRAME_REFERENCE_MD,
+                "references/canvas.md": CANVAS_REFERENCE_MD,
+                "references/document-quality.md": DOCUMENT_QUALITY_REFERENCE_MD,
+                "references/exemplar.md": EXEMPLAR_REFERENCE_MD,
+            },
+            "visual-recap": { "references/wireframe.md": WIREFRAME_REFERENCE_MD },
         },
         manifest: normalizeAppSkillManifest({
             schemaVersion: 1,
@@ -2617,10 +1748,10 @@ export const BUILT_IN_APP_SKILLS = {
                 url: "https://plan.agent-native.com",
                 mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
             },
-            mcp: { serverName: "agent-native-plans" },
+            mcp: { serverName: "plan", aliases: ["agent-native-plans"] },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add the /visual-plan, /visual-recap, /ui-plan, /prototype-plan, /plan-design, and /visual-questions skills plus the Plan MCP connector. Authenticate only for hosted/account-backed sharing.",
+                setup: "Install with the Agent-Native CLI to add the /visual-plan and /visual-recap skills plus the Plan MCP connector. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
@@ -2635,30 +1766,6 @@ export const BUILT_IN_APP_SKILLS = {
                     path: "/plans",
                     description: "Create a visual recap plan from a PR, commit, branch, or git diff for high-altitude review.",
                 },
-                {
-                    id: "ui-plan",
-                    action: "create-ui-plan",
-                    path: "/plans",
-                    description: "Create a UI-first Agent-Native plan with an optional top pan/zoom wireframe canvas and a refined rich document below.",
-                },
-                {
-                    id: "prototype-plan",
-                    action: "create-prototype-plan",
-                    path: "/plans",
-                    description: "Create a prototype-first Agent-Native plan with a functional live prototype above the document.",
-                },
-                {
-                    id: "plan-design",
-                    action: "create-plan-design",
-                    path: "/plans",
-                    description: "Create a full-fidelity Agent-Native design plan with a Design canvas tab and optional matching Prototype tab.",
-                },
-                {
-                    id: "visual-questions",
-                    action: "create-visual-questions",
-                    path: "/plans",
-                    description: "Create a rich visual intake questionnaire for explicit /visual-questions workflows.",
-                },
             ],
             skills: [
                 {
@@ -2671,26 +1778,6 @@ export const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "visual-recap",
                 },
-                {
-                    path: "skills/visual-questions",
-                    visibility: "exported",
-                    exportAs: "visual-questions",
-                },
-                {
-                    path: "skills/ui-plan",
-                    visibility: "exported",
-                    exportAs: "ui-plan",
-                },
-                {
-                    path: "skills/prototype-plan",
-                    visibility: "exported",
-                    exportAs: "prototype-plan",
-                },
-                {
-                    path: "skills/plan-design",
-                    visibility: "exported",
-                    exportAs: "plan-design",
-                },
             ],
             hostAdapters: [
                 "codex-plugin",
@@ -2736,6 +1823,7 @@ export const BUILT_IN_APP_SKILLS = {
         skillMarkdown: CONTEXT_XRAY_SKILL_MD,
     },
 };
+export const AGENT_NATIVE_SKILL_METADATA_FILE = "agent-native-skill.json";
 const BUILT_IN_APP_SKILL_ALIASES = {
     assets: "assets",
     asset: "assets",
@@ -2758,13 +1846,6 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "visual-recaps": "visual-plans",
     "code-review-recap": "visual-plans",
     "code-review-recaps": "visual-plans",
-    "ui-plan": "visual-plans",
-    "prototype-plan": "visual-plans",
-    "plan-design": "visual-plans",
-    "plan-designs": "visual-plans",
-    "design-plan": "visual-plans",
-    "design-plans": "visual-plans",
-    "visual-questions": "visual-plans",
     "html-plan": "visual-plans",
     "plan-mode": "visual-plans",
     plannotate: "visual-plans",
@@ -2788,10 +1869,6 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
         "visual-plan",
         "visual-recap",
         "code-review-recap",
-        "ui-plan",
-        "prototype-plan",
-        "plan-design",
-        "visual-questions",
         "html-plan",
         "plannotate",
     ],
@@ -2824,9 +1901,243 @@ function isLocalOnlyBuiltInSkill(entry) {
 function builtInExtraSkills(entry) {
     return "extraSkills" in entry && entry.extraSkills ? entry.extraSkills : {};
 }
+/**
+ * Sibling reference files for a skill (skill name -> relative path -> content),
+ * materialized alongside its SKILL.md for progressive disclosure.
+ */
+function builtInExtraFiles(entry) {
+    return "extraFiles" in entry && entry.extraFiles ? entry.extraFiles : {};
+}
 function builtInSkillNames(entry) {
     return [entry.skillName, ...Object.keys(builtInExtraSkills(entry))];
 }
+function stableSkillHash(files) {
+    const hash = createHash("sha256");
+    for (const rel of Object.keys(files).sort()) {
+        if (rel === AGENT_NATIVE_SKILL_METADATA_FILE)
+            continue;
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(files[rel]);
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+function skillFilesForBuiltIn(appSkillId) {
+    const entry = BUILT_IN_APP_SKILLS[appSkillId];
+    const skills = {
+        [entry.skillName]: entry.skillMarkdown,
+        ...builtInExtraSkills(entry),
+    };
+    const extraFiles = builtInExtraFiles(entry);
+    const out = {};
+    for (const [skillName, skillMarkdown] of Object.entries(skills)) {
+        const files = {
+            "SKILL.md": skillMarkdown,
+            ...(extraFiles[skillName] ?? {}),
+        };
+        out[skillName] = {
+            appSkillId,
+            displayName: entry.manifest.displayName,
+            skillName,
+            mcpUrl: isLocalOnlyBuiltInSkill(entry)
+                ? ""
+                : entry.manifest.hosted.mcpUrl,
+            files,
+            contentHash: stableSkillHash(files),
+        };
+    }
+    return out;
+}
+function latestSkillBundlesForTargets(appSkillIds) {
+    const out = {};
+    for (const appSkillId of appSkillIds) {
+        Object.assign(out, skillFilesForBuiltIn(appSkillId));
+    }
+    return out;
+}
+function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    for (const [rel, content] of Object.entries(bundle.files)) {
+        const target = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content, "utf-8");
+    }
+    const metadata = {
+        schemaVersion: 1,
+        source: "agent-native",
+        appSkillId: bundle.appSkillId,
+        displayName: bundle.displayName,
+        skillName: bundle.skillName,
+        contentHash: bundle.contentHash,
+        mcpUrl: bundle.mcpUrl,
+        installedAt,
+        updateCommand: `agent-native skills update ${bundle.skillName}`,
+    };
+    fs.writeFileSync(path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+}
+function listSkillFolderFiles(dir) {
+    const out = {};
+    const walk = (current, prefix = "") => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const abs = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs, rel);
+                continue;
+            }
+            if (!entry.isFile() || rel === AGENT_NATIVE_SKILL_METADATA_FILE)
+                continue;
+            out[rel] = fs.readFileSync(abs, "utf-8");
+        }
+    };
+    if (fs.existsSync(dir))
+        walk(dir);
+    return out;
+}
+function readSkillInstallMetadata(dir) {
+    const file = path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE);
+    if (!fs.existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (parsed &&
+            parsed.source === "agent-native" &&
+            typeof parsed.skillName === "string" &&
+            typeof parsed.contentHash === "string") {
+            return parsed;
+        }
+    }
+    catch { }
+    return undefined;
+}
+function homeDir() {
+    return process.env.HOME || os.homedir();
+}
+function skillSearchRoots(input) {
+    const roots = [];
+    const clientSet = new Set(input.clients);
+    const includeAll = input.clients.length === 0;
+    const hasClient = (client) => includeAll || clientSet.has(client);
+    const add = (root, scope, client) => {
+        if (root)
+            roots.push({ root, scope, client });
+    };
+    if (input.scopes.includes("project")) {
+        if (hasClient("codex")) {
+            add(path.join(input.baseDir, ".agents", "skills"), "project", "codex");
+        }
+        if (hasClient("claude-code") || hasClient("claude-code-cli")) {
+            add(path.join(input.baseDir, ".claude", "skills"), "project", "claude-code");
+        }
+        if (includeAll)
+            add(path.join(input.baseDir, "skills"), "project", "repo");
+    }
+    if (input.scopes.includes("user")) {
+        const home = homeDir();
+        if (hasClient("codex")) {
+            add(process.env.CODEX_HOME
+                ? path.join(process.env.CODEX_HOME, "skills")
+                : undefined, "user", "codex");
+            add(home ? path.join(home, ".codex", "skills") : undefined, "user", "codex");
+        }
+        if (hasClient("claude-code") || hasClient("claude-code-cli")) {
+            add(home ? path.join(home, ".claude", "skills") : undefined, "user", "claude-code");
+        }
+    }
+    const seen = new Set();
+    return roots.filter((entry) => {
+        const key = `${entry.scope}:${entry.client}:${path.resolve(entry.root)}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function targetIdsForStatus(parsed) {
+    if (!parsed.target) {
+        return Object.keys(BUILT_IN_APP_SKILLS).filter((id) => !isLocalOnlyBuiltInSkill(BUILT_IN_APP_SKILLS[id]));
+    }
+    const known = normalizeKnownSkillTarget(parsed.target);
+    if (!known) {
+        throw new Error(`Unknown built-in skill: ${parsed.target}. Run "agent-native skills list".`);
+    }
+    if (isLocalOnlyBuiltInSkill(BUILT_IN_APP_SKILLS[known])) {
+        throw new Error(`${BUILT_IN_APP_SKILLS[known].manifest.displayName} is installed as a local command and cannot be refreshed with skills update yet.`);
+    }
+    return [known];
+}
+function scopeFilterForStatus(parsed) {
+    return parsed.scopeExplicit
+        ? [parsed.scope]
+        : ["project", "user"];
+}
+function clientFilterForStatus(parsed) {
+    return parsed.clientExplicit ? resolveClients(parsed.client) : [];
+}
+function collectSkillInstallStates(parsed, options) {
+    const appSkillIds = targetIdsForStatus(parsed);
+    const latest = latestSkillBundlesForTargets(appSkillIds);
+    const roots = skillSearchRoots({
+        baseDir: options.baseDir ?? process.cwd(),
+        clients: clientFilterForStatus(parsed),
+        scopes: scopeFilterForStatus(parsed),
+    });
+    const states = [];
+    const seenDirs = new Set();
+    for (const root of roots) {
+        for (const bundle of Object.values(latest)) {
+            const dir = path.join(root.root, bundle.skillName);
+            const resolvedDir = path.resolve(dir);
+            if (seenDirs.has(resolvedDir) || !fs.existsSync(dir))
+                continue;
+            if (!fs.existsSync(path.join(dir, "SKILL.md")))
+                continue;
+            seenDirs.add(resolvedDir);
+            const files = listSkillFolderFiles(dir);
+            const installedHash = Object.keys(files).length > 0 ? stableSkillHash(files) : null;
+            const metadata = readSkillInstallMetadata(dir);
+            states.push({
+                appSkillId: bundle.appSkillId,
+                displayName: bundle.displayName,
+                skillName: bundle.skillName,
+                path: dir,
+                root: root.root,
+                scope: root.scope,
+                client: root.client,
+                latestHash: bundle.contentHash,
+                installedHash,
+                metadataHash: metadata?.contentHash,
+                current: installedHash === bundle.contentHash,
+                managed: metadata?.source === "agent-native",
+            });
+        }
+    }
+    return states.sort((a, b) => `${a.skillName}:${a.path}`.localeCompare(`${b.skillName}:${b.path}`));
+}
+function updateSkillInstallStates(states, dryRun) {
+    const latest = latestSkillBundlesForTargets([
+        ...new Set(states.map((state) => state.appSkillId)),
+    ]);
+    const updated = [];
+    for (const state of states) {
+        if (state.current && state.managed)
+            continue;
+        const bundle = latest[state.skillName];
+        if (!bundle)
+            continue;
+        if (!dryRun)
+            writeSkillFolder(state.path, bundle);
+        updated.push({
+            ...state,
+            current: !dryRun,
+            installedHash: dryRun ? state.installedHash : bundle.contentHash,
+            metadataHash: dryRun ? state.metadataHash : bundle.contentHash,
+        });
+    }
+    return updated;
+}
 function normalizeClientIds(values) {
     if (!Array.isArray(values))
         return [];
@@ -2860,6 +2171,31 @@ function skillPromptOptions() {
         hint: entry.manifest.description,
     }));
 }
+function prVisualRecapWorkflowPath(baseDir) {
+    return path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml");
+}
+function prVisualRecapWorkflowDisplayPath() {
+    return path.join(".github", "workflows", "pr-visual-recap.yml");
+}
+function prVisualRecapInstallCommand() {
+    return "agent-native skills add visual-plan --with-github-action";
+}
+function prVisualRecapSetupCommand() {
+    return "agent-native recap setup";
+}
+async function promptForGithubAction(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.confirm({
+        message: "Optional: add automatic PR Visual Recaps?\n" +
+            `  This writes ${context.workflowPath}; ${context.setupCommand} can finish GitHub secrets.`,
+        initialValue: false,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Skipped PR Visual Recap workflow.");
+        return null;
+    }
+    return Boolean(result);
+}
 function shouldPrompt(parsed, options) {
     if (parsed.yes || parsed.printJson)
         return false;
@@ -2944,7 +2280,10 @@ export function parseSkillsArgs(argv) {
         command = "help";
         args = argv.slice(1);
     }
-    else if (first === "list" || first === "add") {
+    else if (first === "list" ||
+        first === "add" ||
+        first === "status" ||
+        first === "update") {
         command = first;
         args = argv.slice(1);
     }
@@ -2956,6 +2295,7 @@ export function parseSkillsArgs(argv) {
         client: "codex",
         clientExplicit: false,
         scope: "user",
+        scopeExplicit: false,
         yes: false,
         dryRun: false,
         printJson: false,
@@ -2986,8 +2326,10 @@ export function parseSkillsArgs(argv) {
             out.client = value;
             out.clientExplicit = true;
         }
-        else if ((value = eat("--scope")) !== undefined)
+        else if ((value = eat("--scope")) !== undefined) {
             out.scope = value;
+            out.scopeExplicit = true;
+        }
         else if ((value = eat("--mcp-url")) !== undefined)
             out.mcpUrl = value;
         else if (arg === "--yes" || arg === "-y")
@@ -3031,14 +2373,9 @@ function loadSkillTarget(target) {
             },
             skillNames,
             materializeInstructions(outDir) {
-                const skills = {
-                    [builtIn.skillName]: builtIn.skillMarkdown,
-                    ...builtInExtraSkills(builtIn),
-                };
-                for (const [skillName, skillMarkdown] of Object.entries(skills)) {
-                    const skillDir = path.join(outDir, "skills", skillName);
-                    fs.mkdirSync(skillDir, { recursive: true });
-                    fs.writeFileSync(path.join(skillDir, "SKILL.md"), skillMarkdown, "utf-8");
+                const bundles = skillFilesForBuiltIn(knownTarget);
+                for (const bundle of Object.values(bundles)) {
+                    writeSkillFolder(path.join(outDir, "skills", bundle.skillName), bundle);
                 }
                 return outDir;
             },
@@ -3136,6 +2473,8 @@ function dryRunInstallCommand(parsed, target) {
         args.push("--mcp-only");
     if (!parsed.connect)
         args.push("--no-connect");
+    if (parsed.withGithubAction)
+        args.push("--with-github-action");
     if (parsed.yes || isKnownSkill(target))
         args.push("--yes");
     return commandString("agent-native", args);
@@ -3292,6 +2631,9 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         const clients = parsed.clients ?? resolveClients(parsed.client);
         const skillsAgents = skillsAgentsForClients(clients);
         if (parsed.dryRun) {
+            const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
+                ? prVisualRecapWorkflowDisplayPath()
+                : undefined;
             return {
                 id: knownBuiltIn.manifest.id,
                 displayName: knownBuiltIn.manifest.displayName,
@@ -3302,6 +2644,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 dryRun: true,
                 local: true,
                 commands: [dryRunInstallCommand(parsed, target)],
+                githubActionPath,
             };
         }
         const localInstall = installLocalContextXray({
@@ -3333,6 +2676,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
         try {
+            const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
+                ? prVisualRecapWorkflowDisplayPath()
+                : undefined;
+            const githubActionSuggestedCommand = knownTarget === "visual-plans" && !parsed.withGithubAction
+                ? prVisualRecapInstallCommand()
+                : undefined;
             return {
                 id: installTarget.id,
                 displayName: installTarget.displayName,
@@ -3342,6 +2691,8 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 mcpClients: clients,
                 dryRun: true,
                 commands: [dryRunInstallCommand(parsed, target)],
+                githubActionPath,
+                githubActionSuggestedCommand,
             };
         }
         finally {
@@ -3409,14 +2760,32 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         }
         // `--with-github-action`: also drop the PR Visual Recap workflow into the
         // repo so PRs get automatic recaps. Only meaningful for the plan family.
+        const baseDir = options.baseDir ?? process.cwd();
+        let withGithubAction = Boolean(parsed.withGithubAction);
         let githubActionPath;
         let githubActionExisted;
-        if (parsed.withGithubAction) {
+        let githubActionSuggestedCommand;
+        if (knownTarget === "visual-plans" &&
+            !withGithubAction &&
+            !fs.existsSync(prVisualRecapWorkflowPath(baseDir))) {
+            if (shouldPrompt(parsed, options)) {
+                const prompt = options.promptGithubAction ?? promptForGithubAction;
+                withGithubAction =
+                    (await prompt({
+                        workflowPath: prVisualRecapWorkflowDisplayPath(),
+                        setupCommand: prVisualRecapSetupCommand(),
+                    })) === true;
+            }
+            if (!withGithubAction) {
+                githubActionSuggestedCommand = prVisualRecapInstallCommand();
+            }
+        }
+        if (withGithubAction) {
             if (knownTarget !== "visual-plans") {
                 options.log?.("--with-github-action only applies to the visual-plan skill; skipping the workflow.");
             }
             else {
-                const written = writePrVisualRecapWorkflow(options.baseDir ?? process.cwd());
+                const written = writePrVisualRecapWorkflow(baseDir);
                 githubActionPath = written.path;
                 githubActionExisted = written.existed;
                 commands.push(`write ${written.path}`);
@@ -3436,6 +2805,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             connectCommand,
             githubActionPath,
             githubActionExisted,
+            githubActionSuggestedCommand,
         };
     }
     finally {
@@ -3453,6 +2823,68 @@ function listSkills() {
         local: isLocalOnlyBuiltInSkill(entry),
     }));
 }
+function skillStateJson(state) {
+    return {
+        appSkillId: state.appSkillId,
+        displayName: state.displayName,
+        skillName: state.skillName,
+        path: state.path,
+        scope: state.scope,
+        client: state.client,
+        status: state.current ? "current" : "stale",
+        managed: state.managed,
+        installedHash: state.installedHash,
+        latestHash: state.latestHash,
+        metadataHash: state.metadataHash,
+    };
+}
+function formatSkillState(state) {
+    const status = state.current ? "current" : "stale";
+    const managed = state.managed ? "managed" : "unmarked";
+    const hashes = state.installedHash && !state.current
+        ? ` (${state.installedHash} -> ${state.latestHash})`
+        : "";
+    return `${state.skillName.padEnd(22)} ${status.padEnd(7)} ${state.scope}/${state.client} ${managed}${hashes}\n  ${state.path}`;
+}
+function runSkillsStatusOrUpdate(parsed, options, update) {
+    const before = collectSkillInstallStates(parsed, options);
+    const changed = update ? updateSkillInstallStates(before, parsed.dryRun) : [];
+    const after = update && !parsed.dryRun
+        ? collectSkillInstallStates(parsed, options)
+        : before;
+    if (parsed.printJson) {
+        const outputStates = update && !parsed.dryRun ? after : before;
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: parsed.command,
+            dryRun: parsed.dryRun,
+            found: before.length,
+            stale: outputStates.filter((state) => !state.current).length,
+            updated: changed.length,
+            skills: outputStates.map(skillStateJson),
+        }, null, 2)}\n`);
+        return;
+    }
+    if (before.length === 0) {
+        const target = parsed.target ? ` for ${parsed.target}` : "";
+        process.stdout.write(`No installed Agent Native skill copies found${target}.\nRun "agent-native skills add ${parsed.target ?? "visual-plan"}" to install one.\n`);
+        return;
+    }
+    if (update) {
+        if (parsed.dryRun) {
+            process.stdout.write(changed.length
+                ? `Would update ${changed.length} skill folder${changed.length === 1 ? "" : "s"}:\n`
+                : "All discovered skill folders are already current.\n");
+        }
+        else {
+            process.stdout.write(changed.length
+                ? `Updated ${changed.length} skill folder${changed.length === 1 ? "" : "s"}.\n`
+                : "All discovered skill folders are already current.\n");
+        }
+    }
+    const rows = (update && parsed.dryRun ? before : after).map(formatSkillState);
+    process.stdout.write(`${rows.join("\n")}\n`);
+}
 export async function runSkills(argv, options = {}) {
     const parsed = parseSkillsArgs(argv);
     const log = parsed.printJson
@@ -3478,6 +2910,10 @@ export async function runSkills(argv, options = {}) {
         }
         return;
     }
+    if (parsed.command === "status" || parsed.command === "update") {
+        runSkillsStatusOrUpdate(parsed, options, parsed.command === "update");
+        return;
+    }
     const targets = await resolveSkillTargets(parsed, options);
     if (!targets)
         return;
@@ -3536,7 +2972,15 @@ export async function runSkills(argv, options = {}) {
             .filter((p) => Boolean(p))),
     ];
     const githubActionLine = githubActions.length
-        ? `PR Visual Recap workflow: wrote ${githubActions.join(", ")}.\nSet these GitHub repo secrets/variables for it to run:\n  ${PR_VISUAL_RECAP_SETUP.join("\n  ")}`
+        ? `PR Visual Recap workflow: wrote ${githubActions.join(", ")}.\nNext: run ${prVisualRecapSetupCommand()} to configure GitHub secrets/variables, or set them manually:\n  ${PR_VISUAL_RECAP_SETUP.join("\n  ")}`
+        : "";
+    const githubActionSuggestions = [
+        ...new Set(results
+            .map((result) => result.githubActionSuggestedCommand)
+            .filter((command) => Boolean(command))),
+    ];
+    const githubActionSuggestionLine = githubActionSuggestions.length
+        ? `Optional PR Visual Recap workflow: run ${githubActionSuggestions.join(" && ")} to add automatic recap comments on pull requests.`
         : "";
     process.stdout.write([
         `Installed ${installedNames} skill${results.length === 1 ? "" : "s"}.`,
@@ -3551,6 +2995,7 @@ export async function runSkills(argv, options = {}) {
             : "",
         authLine,
         githubActionLine,
+        githubActionSuggestionLine,
         localCommands.length ? `Local command: ${localCommands.join(", ")}.` : "",
         "Restart or reload selected agent clients if the skill is not visible yet.",
         parsed.clientExplicit