From 32059d5c75f96cce476f71d5b531ca7e67f724dc Mon Sep 17 00:00:00 2001
From: andrmaz <60042277+andrmaz@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:10:54 +0200
Subject: [PATCH] Add visual-recap skill and documentation

- Introduced the `/visual-recap` skill to generate interactive visual recaps from PRs, branches, or commits, enhancing the review process with annotated diffs, diagrams, and summaries.
- Added comprehensive documentation in `README.md`, `SKILL.md`, and various reference files to guide users on functionality, usage scenarios, and local-files privacy mode.
- Updated `skills-lock.json` to include the new skill entry.

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
---
 .agents/skills/visual-recap/README.md         | 103 ++++
 .agents/skills/visual-recap/SKILL.md          | 552 ++++++++++++++++++
 .../visual-recap/references/connection.md     |  51 ++
 .../visual-recap/references/local-files.md    |  99 ++++
 .../visual-recap/references/wireframe.md      | 312 ++++++++++
 skills-lock.json                              |   6 +
 6 files changed, 1123 insertions(+)
 create mode 100644 .agents/skills/visual-recap/README.md
 create mode 100644 .agents/skills/visual-recap/SKILL.md
 create mode 100644 .agents/skills/visual-recap/references/connection.md
 create mode 100644 .agents/skills/visual-recap/references/local-files.md
 create mode 100644 .agents/skills/visual-recap/references/wireframe.md

diff --git a/.agents/skills/visual-recap/README.md b/.agents/skills/visual-recap/README.md
new file mode 100644
index 0000000..f0056ea
--- /dev/null
+++ b/.agents/skills/visual-recap/README.md
@@ -0,0 +1,103 @@
+# /visual-recap
+
+Turn a branch, commit, or PR diff into an interactive visual recap with
+annotated diffs, diagrams, API/schema summaries, file maps, UI state summaries,
+and focused review notes.
+
+`/visual-recap` is the reverse of `/visual-plan`: instead of planning a future
+change, it summarizes a diff, branch, commit, or PR after the work exists. The
+goal is to help reviewers understand the shape of a change before they dive into
+raw line-by-line diffs.
+
+It solves for diffs that hide the shape of the change. Reviewers can understand
+contracts, architecture moves, schema changes, and UI impact before diving into
+raw line-by-line review.
+
+The recap is a human-optimized MDX document with custom components for the
+things raw diffs are bad at explaining: annotated diffs, diagrams, visual schema
+maps, OpenAPI-style API diffs, file maps, UI state summaries, and focused review
+notes.
+
+Visual recaps are MDX, customizable with your own components, and viewed with
+the [Agent-Native plans app](https://www.agent-native.com/docs/template-plan).
+The hosted app is 100% free and open source; local-files mode writes the recap
+MDX locally, starts a localhost bridge, and opens the hosted Plan UI with no
+sharing.
+[Source here](https://github.com/BuilderIO/agent-native/).
+
+<picture>
+  <img alt="Visual recap review surface animation" src="../../media/visual-recap.gif">
+</picture>
+
+## What It Does
+
+- Reads the actual changed files and diff.
+- Publishes an interactive recap with file maps, diagrams, visual schema
+  maps, API diffs, annotated diffs, UI state summaries, and focused key changes.
+- Keeps recaps substantial enough for real review without dumping every line.
+- Makes large changes consumable before a reviewer opens raw GitHub diff view.
+- Can be installed with a reusable GitHub Action for PR visual recaps.
+
+## When To Use It
+
+Use it for PRs or work units that are large, multi-file, UI-heavy, or touch
+schema, API contracts, permissions, architecture, or review-critical behavior.
+
+Skip it for tiny, obvious diffs that review faster directly in GitHub.
+
+## What Reviewers Get
+
+Reviewers get the shape of the change first: what moved, which contracts
+changed, what data or API surfaces were touched, how UI states differ, and where
+the risky lines are. Then they can review the raw diff with a map in their head.
+
+## Modes
+
+`/visual-recap` can run in three modes:
+
+- **Hosted Plans, shareable links (recommended):** uses the free, open-source
+  Agent-Native plans app at plan.agent-native.com for shareable links, comments,
+  and the browser editor.
+- **Local files only:** writes a local MDX folder, starts a localhost bridge,
+  and opens the hosted Plan UI against that local source. No sharing, all local,
+  and no recap content is written to the hosted database.
+- **Self-hosted/custom URL:** connects the skill to your own Plan app or local
+  development tunnel.
+
+Use hosted mode when you want comments and shareable links. Use local files mode
+when the recap should live in source control or stay on your machine. Use
+`plans/<slug>/` when you want to check the files in, or a temp/ignored folder
+when you do not. The bridge URL works on the machine running it and is not a
+share link.
+
+## GitHub Action
+
+When installed with `--with-github-action`, this repo writes a PR workflow that
+can automatically generate a visual recap from every pull request diff.
+Reviewers open the generated PR recap in the
+[Plan app review surface](https://www.agent-native.com/docs/template-plan)
+before moving into raw GitHub diff view.
+
+The top-level installer also offers the PR action as an option:
+
+```sh
+npx @agent-native/skills@latest add
+```
+
+![Example of a visual recap posted to a PR](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcf9bac396cf24a4ba976fc331af6fc5d)
+
+## Install
+
+```sh
+npx @agent-native/skills@latest add --skill visual-recap --with-github-action
+```
+
+The interactive installer asks whether to use hosted Plans or local files. To
+force the no-sharing local path:
+
+```sh
+npx @agent-native/skills@latest add --skill visual-recap --mode local-files
+```
+
+The skill expects the [Plan MCP connector](https://www.agent-native.com/docs/template-plan)
+to be available when hosted mode is used.
diff --git a/.agents/skills/visual-recap/SKILL.md b/.agents/skills/visual-recap/SKILL.md
new file mode 100644
index 0000000..d9069ce
--- /dev/null
+++ b/.agents/skills/visual-recap/SKILL.md
@@ -0,0 +1,552 @@
+---
+name: visual-recap
+description: >-
+  Turn a PR, branch, commit, or git diff into an interactive visual recap with
+  diagrams, file maps, API/schema summaries, annotated diffs, and focused review
+  notes.
+metadata:
+  visibility: exported
+---
+
+# Visual Recap
+
+`/visual-recap` creates a visual plan built **from** a diff, not toward one. It
+is the reverse of forward planning: instead of describing the change you are
+about to make, you describe the change that was just made, at a higher altitude
+than line-by-line review. The same plan data model serves both directions —
+schema, API, file, and architecture changes become the same `data-model`,
+`api-endpoint`, `file-tree`, and `diagram` blocks a forward plan would use, only
+now they summarize work that exists. A reviewer scans the shape of the change
+before spending attention on the literal lines.
+
+## Publish As An Agent-Native Plan — Never Inline
+
+The deliverable is ALWAYS a published Agent-Native Plan, created with
+`create-visual-recap` on the Plan MCP connector — NEVER inline chat content (not
+Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the
+recap" summary). A recap's entire value is the hosted, interactive, annotatable
+plan; an inline summary is not a degraded recap, it is the thing a recap
+replaces. If the `plan` (or legacy `agent-native-plans`) tools are not visible,
+discover them through the host's `tool_search` first; if they are still missing,
+STOP and give the user the client-specific reconnect step rather than improvising
+an inline recap. Before publishing, or whenever a connector or auth error
+appears, READ `references/connection.md` in this skill directory — it is the
+single source of truth for the never-inline rule, connector discovery, and the
+per-client reconnect steps. Local-files privacy mode (below) is the one
+exception.
+
+## Local-Files Privacy Mode — read `references/local-files.md`
+
+When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
+publish, fully local/offline/private recaps, or `AGENT_NATIVE_PLANS_MODE=local-files`
+— do not call any hosted Plan tool except the schema-only `get-plan-blocks`
+catalog lookup. Read the diff with the local `recap collect-diff` / `scan` /
+`build-prompt --local-files` helpers, author a local MDX folder (set
+`kind: "recap"` and `localOnly: true`), and preview it with `plan local check`,
+`plan local serve --kind recap`, and `plan local verify --kind recap`. Before
+using local-files mode, READ `references/local-files.md` in this skill directory
+— it is the single source of truth for the full contract.
+
+## When To Use
+
+Build a recap when a PR or commit is large, multi-file, or touches schema, API
+contracts, or architecture, and a reviewer would benefit from seeing the change
+mapped to structured blocks before reading the raw diff. A GitHub Action can
+generate one automatically from a PR diff; an agent can generate one on request
+("recap this PR", "show me what this branch changed"). Skip it for small,
+single-file, or obvious diffs — a recap is review overhead, and a tiny change
+reviews faster as plain diff.
+
+## Recap The Whole Work Unit
+
+When `/visual-recap` is invoked in a chat thread after work has already happened,
+the default scope is the whole current work unit/thread, not only the most recent
+user message, tool action, or follow-up fix. Gather the thread-owned changes
+across the conversation: original implementation work, later bug fixes, UI
+follow-ups, tests, changesets, skill/instruction updates, generated plan/source
+artifacts, and any local import/linking fixes needed to make the recap open.
+
+Use the current diff plus conversation context to separate thread-owned changes
+from unrelated dirty work that existed before the thread. Exclude unrelated
+pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred,
+state the assumption or ask a concise question before publishing.
+
+When updating an existing recap after feedback, revise the recap so it still
+covers the whole thread/work unit plus the new correction. Do not replace a broad
+recap with a narrow recap of only the latest feedback unless the user explicitly
+asks for that narrower scope.
+
+## Keep The Recap Body Lean
+
+Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to
+the generated plan body. In particular, do not create a `rich-text` block just to
+say the recap is an aid, that the reviewer should still review the diff, how many
+files changed, or which ref/working tree generated the recap. The plan title,
+brief, and `file-tree` (which carries the per-file change stats) already carry
+that context.
+
+Only add prose blocks when they tell the reviewer something specific about the
+change that the structured blocks do not: the objective, a real compatibility
+risk, an important decision visible in the diff, or a grounded review note.
+
+## Recaps Must Be Substantial
+
+Lean is not the same as thin. A recap is not a single wireframe plus one
+sentence — that under-serves the reviewer as much as boilerplate prose over-serves
+them. Alongside the visual/structural headline (wireframes, `data-model`,
+`api-endpoint`, `diagram`), a substantial recap also carries the implementation
+evidence:
+
+- A short surface/state inventory before authoring: list the changed routes,
+  components, popovers/dialogs, role/access states, empty/error states, and
+  shared abstractions visible in the diff. The final recap must either represent
+  each meaningful item with a block or intentionally omit it because it is tiny,
+  redundant, or not user-visible.
+- A `file-tree` of the changed files with each entry's `change` flag, so the
+  reviewer sees the footprint of the work at a glance.
+- The split `diff` of the KEY changed files, grouped under a `## Key changes`
+  `rich-text` heading in a single horizontal `tabs` block (the default
+  orientation, one file per tab), with a one-line `summary` and a few
+  `annotations` on each — so the reviewer can drop from the high-altitude shape
+  straight into the load-bearing code. Use horizontal file tabs, not a vertical
+  side rail, so the selected file has enough width for the side-by-side diff.
+
+Skip the diff appendix only for a genuinely tiny change that reviews faster as
+plain diff (see "When To Use"); for any change worth recapping, the file-tree and
+key-change diffs belong in the plan.
+
+## Canonical Shape And Budgets
+
+A strong recap follows one skeleton, top to bottom:
+
+1. UI-impact headline — wireframes first, when the diff changed rendered UI.
+2. Short outcome narrative (`rich-text`): what changed and why, 1-3 paragraphs.
+3. `data-model` / `api-endpoint` blocks for schema and contract changes.
+4. `file-tree` of the changed files with `change` flags.
+5. `## Key changes` — one horizontal `tabs` block of `diff` / `annotated-code`.
+
+Budgets that keep the recap reviewable:
+
+- 3-8 key-change tabs. Fewer than 3 on a large change under-serves the
+  reviewer; more than 8 stops being a summary.
+- Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per
+  tab; summarize or link the rest of a long file instead of dumping it.
+- Title at most ~70 characters; brief 1-3 sentences.
+
+These budgets are also the cost ceiling: do not exceed them in the name of
+thoroughness, and do not re-read the full diff after the initial sequential
+pass — work from the notes taken during that pass.
+
+**GOOD.** A 25-file auth change: Before/After wireframes of the login surface,
+a two-paragraph narrative, a diff-aware `data-model` of the sessions table, an
+`api-endpoint` for the new refresh route, a `file-tree` with change flags, and
+`## Key changes` with five focused tabs, each with a one-line `summary` and a
+few annotations on the load-bearing hunks.
+
+**BAD.** One giant unsegmented diff dump with no summaries or annotations; or a
+sparse three-block recap of a 40-file change (one wireframe, one sentence, one
+file list) that forces the reviewer back into the raw diff anyway.
+
+## UI Impact Needs Wireframes
+
+When the diff changes rendered UI, layout, density, visual state, interaction
+affordances, navigation, controls, menus, dialogs, or design tokens, the recap
+MUST include one or more wireframes. Prose and file diffs are not a substitute
+for showing what changed visually.
+
+Before choosing wireframes, make a UI coverage pass from the diff:
+
+- Identify the entry surface where the change appears, such as a page header,
+  list row, toolbar, route shell, or menu trigger.
+- Identify the interaction surface that opens or changes, such as a popover,
+  dialog, tab, sheet, dropdown, inline editor, or toast.
+- Identify the resulting destination or persistent state, such as a public page,
+  read-only view, empty state, error state, loading state, permission-denied
+  state, or saved/shared state.
+- Identify access or role variants when permissions change. Owner/admin/editor
+  versus viewer/non-manager differences are visual behavior and need a compact
+  matrix, paired wireframes, or clearly labeled state sequence.
+
+For UI-heavy PRs, a single before/after of the entry surface is not enough.
+Show the changed entry point, the main changed interaction surface, and the
+resulting/destination state. Add more states when the diff adds tabs, role-based
+controls, public/private visibility, invite/manage flows, destructive controls,
+or empty/error branches.
+
+Choose the smallest visual surface that makes the review clear:
+
+- Use a `Before` / `After` wireframe pair when the reviewer benefits from direct
+  comparison, such as a removed or added control, a changed state, layout
+  density, ordering, navigation, or a visible component replacement.
+  `references/wireframe.md` owns how to lay that pair out (columns vs.
+  vertical stack by geometry).
+- Use an after-only wireframe when the change is purely additive or the "before"
+  state would only show absence without adding review value.
+- Use more than two wireframes when the UI change is flow-dependent, responsive,
+  or stateful; show the meaningful states in order instead of forcing a single
+  before/after pair.
+- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
+  matching `surface` (`popover`, `panel`, etc.) and show the focused sub-surface.
+  Do not redraw a full page unless placement in the page is itself part of the
+  change.
+
+Ground each wireframe in the changed UI behavior, component names, file paths,
+and diff-visible labels/states. If exact pixels are inferred rather than
+captured, say so in the wireframe caption or a concise annotation. For
+local/manual recaps, import or update the plan source that holds the wireframes
+so the rendered recap opens with the UI visual available.
+
+## Wireframe Quality — read `references/wireframe.md`
+
+UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
+pinned bottom bars, real product content, before/after comparability, the right
+`surface` preset, `--wf-*` tokens instead of hex, and no `<html>`/`<style>`/font
+tags. Before authoring ANY wireframe / `<Screen>` / `WireframeBlock`, READ
+`references/wireframe.md` in this skill directory — it is the single source of
+truth for HTML wireframe quality, shared word for word with `/visual-plan`
+and `/visual-recap`. Do not author wireframes from memory.
+
+Use the standard `WireframeBlock` / `<Screen>` format so the Plan viewer owns the
+surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate
+when placement precision matters, especially popovers, menus, dialogs, and dense
+forms. For HTML
+wireframes, keep `renderMode` unset or `wireframe` unless a design-only editable
+mockup is explicitly required, because `renderMode="design"` disables the
+sketchy rough overlay.
+
+When a browser tool is available, render a UI-impact recap in the Plan viewer
+and visually inspect it at the current theme before sharing. If any label,
+annotation, toolbar, or wireframe content overlaps another element, fix the MDX
+and re-import before reporting the link. Limit this to one render-and-inspect
+pass plus at most one fix-and-re-render; do not keep iterating beyond that
+unless the user explicitly asks. A text-match screenshot is not enough;
+visually inspect the captured image. When no browser is available (for example
+a headless CI agent), state that in the recap handoff instead.
+
+## Top Canvas Recaps — read `../visual-plan/references/canvas.md`
+
+When a recap includes a top canvas, storyboard, or flow view, READ
+`../visual-plan/references/canvas.md` before authoring `canvas.mdx`. Recap
+canvas artboards must use the same HTML wireframe path as good document-body
+wireframes: `<Screen surface="..." html={...} />` with a semantic HTML fragment.
+Do not author fresh kit-tree children such as `<FrameScreen>`, `<Card>`,
+`<Row>`, `<Title>`, or `<Btn>` inside canvas `<Screen>` tags. Those components
+are legacy compatibility markup for old plans; in new canvas storyboards they
+can produce cramped or overlapping layouts even when the inline body wireframe
+looks good. If a canvas mockup looks worse than the same screen below the fold,
+assume it used the legacy kit path and replace it with an HTML screen.
+
+## Open And Report The Recap
+
+In local-files privacy mode, run `plan local check` first, then report the local
+bridge URL from
+`npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open`
+or from `<plan-dir>/.plan-url`. It opens the hosted Plan UI but reads from the
+localhost bridge on this machine, so it is not shareable across machines. If the
+Plan app itself is running locally with the same `PLAN_LOCAL_DIR`, the
+`/local-plans/<slug>` route is also valid. Do not invent a hosted database URL
+and do not publish just to get an absolute Plan link.
+
+After creating the recap, link the reviewer to the rendered plan with an
+**absolute URL on the origin whose database actually holds the plan**. That
+origin is the Plan MCP server you just created the recap through — NOT whatever
+dev server you happen to know is running. The create tool returns the correct
+link; report THAT. Never make the primary link a local `plan.mdx` file, a local
+mirror folder, or a relative path such as `/plans/<id>`.
+
+When the recap is posted to a PR for a private repo, the plan link is not a
+public URL. Make the PR comment/handoff copy explicit: reviewers may need to
+sign in to Agent-Native Plans with an account that has access to the owning
+organization before the link loads. Use wording like: "Private repo recap:
+sign in with access to this org if the plan does not open." Do not imply the
+link is broken or public when access is gated by repo/org visibility.
+
+A recap lives only in the database of the MCP that created it. A separately
+running local dev server (e.g. `http://localhost:8081`) has its OWN database and
+will NOT contain a recap created through the hosted MCP, so a hand-built
+`localhost` link returns "Plan not found". This is the most common recap
+mistake — do not guess an origin you have not confirmed shares the MCP's data.
+
+Resolve the URL in this order:
+
+1. Use the absolute URL the create tool RETURNS — `openLink.webUrl`, else the
+   `visualUrl` in the returned `plan.mdx` frontmatter, else `url`/`path`
+   resolved against the MCP server's own origin (for the hosted MCP that is
+   `https://plan.agent-native.com`). This always points at the database that has
+   the plan.
+2. Use a `localhost`/dev origin ONLY when the recap was created through a Plan
+   MCP bound to that same origin — i.e. that MCP's url is
+   `http://localhost:<port>/mcp`. Creating through the hosted MCP
+   and linking to localhost is the exact mismatch that 404s.
+3. If only a plan id is available, build the MCP origin's absolute URL
+   (hosted: `https://plan.agent-native.com/plans/<id>`) and say it was inferred.
+
+If the user wants to review on localhost but the recap was created through the
+hosted MCP, say so plainly: the local dev server cannot see it. To view a recap
+on localhost (e.g. to exercise un-deployed local renderer changes), they must
+connect a LOCAL Plan MCP (`http://localhost:<port>/mcp`) and
+re-create the recap through it so it lands in the local database; offer to do
+that rather than handing over a localhost URL that will not resolve.
+
+When running in Codex and the Browser/in-app side browser tools are available,
+open the returned absolute recap URL there automatically after creation. Still
+include the same absolute URL in the final response. Local mirror files like
+`plans/<slug>/plan.mdx` may be mentioned only as secondary source-control
+artifacts, not as the main way to open the recap.
+
+## Diff → Block Mapping
+
+Map each kind of change to the block that carries it, derived mechanically from
+the actual diff. The names below are the CONCEPTUAL block types, not the JSX
+tags — resolve every conceptual name to its exact tag + prop schema with the
+`get-plan-blocks` tool (see "Block reference" below) before authoring.
+
+- **Schema / migration change** → `data-model` for the resulting entities,
+  fields, and relations. Flag what moved per field/entity with
+  `change: "added" | "modified" | "removed" | "renamed"`, and for a changed type
+  set `was` to the prior value (e.g. the old column type) — grounded in the real
+  migration diff. That diff-aware `data-model` is the headline; reach for a split
+  `diff` of the literal SQL only when the exact statement still matters, not by
+  default.
+- **API / action / route change** → `api-endpoint` with the method, path,
+  params, request, and responses as they are after the change. Flag each changed
+  param/response with `change` (and `was` on a param whose type/shape changed),
+  and set `change` on the endpoint root for a wholly added or removed route. Mark
+  removed endpoints with `deprecated: true` and explain in prose.
+  Keep multiple API endpoints in the normal single-column document flow unless
+  they are an explicit before/after contract comparison.
+  Author each request/response example as a SINGLE valid JSON value — one
+  top-level object or array, parseable on its own — so it renders in the
+  collapsible JSON explorer. Do not put `//` or `/* */` comments, prose,
+  trailing commas, or two or more concatenated top-level objects inside one
+  example; a non-parseable body falls back to flat text and loses the explorer.
+  When an endpoint has several distinct message shapes (for example separate
+  websocket frame types, or a success body versus an error body), give each its
+  OWN example with its own label rather than cramming them into one body.
+- **Compatibility-sensitive change** → short `rich-text` notes beside the
+  relevant `data-model` / `api-endpoint` block. Name the changed field,
+  endpoint, or behavior and mark whether it is breaking, risky, or non-breaking;
+  pair that note with a split `diff` for the literal lines.
+- **Any meaningful code hunk** → `diff` with `mode: "split"`, carrying the real
+  `before` / `after` text and the `filename` / `language`. Split mode is the
+  default for recap code review because before/after legibility is the point;
+  use `mode: "unified"` only for a genuinely narrow standalone hunk where
+  side-by-side would hide the code. Give every `diff` a one-line `summary`
+  saying what the hunk changes and why; it renders as a description above the
+  code so the reviewer reads intent first. Never leave a diff unlabeled.
+  For the KEY changed files, attach `annotations` to the `diff` so the recap
+  calls out what each important hunk does — this is the headline affordance for
+  annotating the key files updated. Each annotation anchors to the AFTER-side
+  line numbers by default (set `side: "before"` to point at removed lines). Keep
+  it to a few high-signal notes per file, not one per line.
+  When several key files each need a substantial diff, introduce the group with a
+  `rich-text` heading block whose markdown is `## Key changes`, then place the
+  `diff` blocks under it in a reusable `tabs` block with horizontal orientation
+  (the default — omit `orientation`) so the selected file's split diff gets the
+  full document width. Let that heading label the section — do NOT also set a
+  `title` on the `tabs` block. Keep each tab label to the file path or a short
+  basename plus directory hint.
+  The renderer's wide document layout is intentionally allowlisted: `diff`,
+  `annotated-code`, vertical `tabs`, and `tabs` containing diff-like children
+  break out wider than prose. Do not put API endpoints, OpenAPI specs, data
+  models, JSON explorers, wireframes, question forms, or custom HTML into tabs
+  merely to make them wide.
+  If the recap ends with more than one supporting diff, that trailing diff
+  appendix should be one horizontal `tabs` block under its own `## Key changes`
+  heading, not a stack of separate `diff` blocks.
+- **Brand-new file or a substantial added block with no meaningful "before"** →
+  `annotated-code` rather than a one-sided split `diff`. Carry the real new code
+  with its `filename` / `language` and anchor a few high-signal notes to the lines
+  that matter so the reviewer reads what the new code does, not code for code's
+  sake. Keep split `diff` for true before/after hunks where the removed lines
+  still carry meaning, and group several annotated walkthroughs in a horizontal
+  `tabs` block the same way diffs are grouped.
+- **Files added / removed / renamed** → `file-tree` with each entry's `change`
+  flag (`added`, `removed`, `modified`, `renamed`) and a short `note`; attach a
+  `snippet` only when one tells the reviewer something the path does not.
+- **Rendered UI / interaction change** → one or more wireframes showing the
+  visible UI delta before the reviewer reads code. Use `Before` / `After`
+  wireframes when the comparison clarifies the change; otherwise use after-only
+  or a short state/flow sequence. Use realistic UI surfaces: for a popover
+  change, show a popover with its title row, top-right actions, options/fields,
+  tabs, selected/disabled states, people/lists/rows, and any opened prompt/menu
+  anchored to the correct trigger. If a route was added, show the route body and
+  the unavailable/empty state when the diff implements one. If permissions
+  changed, show what managers can do and what viewers/non-managers see instead.
+  Keep the body lean: the wireframe carries the UI story, while the file tree
+  and `diff` blocks carry implementation evidence.
+- **Architecture or data-flow shift** → `diagram` with `data.html` / `data.css`
+  as a two-panel before/after, layered, or swimlane layout, or `mermaid` for a
+  quick graph. Use two-dimensional layouts; do not reduce a structural change to
+  a left-to-right chain. Do not use `diagram` as a stand-in for rendered UI
+  controls; UI changes need `wireframe` blocks.
+  Author diagram HTML/CSS with the renderer-owned `.diagram-*` primitives
+  (`.diagram-panel`, `.diagram-node`, `.diagram-pill`, `[data-rough]`, …) and
+  the same `--wf-*` theme tokens `references/wireframe.md` defines — never
+  `font-family`, hex, rgb/hsl literals, or one-off dark/light palettes. Choose
+  the outer `frame` intentionally: recap diagrams usually benefit from
+  `frame: "show"` when they stand alone, but use `frame: "hide"` when columns,
+  tabs, a card, or the diagram's own panels already provide the boundary.
+- **Outcome-first narrative** → `rich-text` for the "what changed and why" prose:
+  the objective the diff served, the key decisions visible in it, and the risks a
+  reviewer should weigh. This is the only place the model writes freely.
+
+## Block reference — call `get-plan-blocks`, do not memorize tags
+
+The conceptual block names above (`api-endpoint`, `data-model`, `json-explorer`,
+`tabs`, …) are NOT the JSX tags you author with, and the exact tags, required
+fields, and prop shapes change as the block library evolves. Do not author from
+memorized tags — they drift and silently produce a wrong tag (`ApiEndpoint`
+instead of `Endpoint`, `JsonExplorer` instead of `Json`, `Tabs` instead of
+`TabsBlock`) that errors on import.
+
+**Before writing any structured plan content, fetch/read the block catalog.** In
+hosted or self-hosted mode, call `get-plan-blocks` on the Plan MCP connector
+(`plan` or legacy `agent-native-plans`). If no Plan tools are visible yet in a
+lazy-loading client, search/load them through the host's tool discovery surface
+first (`tool_search` when available). In local-files mode, or when the skill was
+installed as plain text and no MCP tools are registered after discovery, run
+`npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+file first. The CLI command calls the public no-auth `get-plan-blocks` route and
+sends no plan/recap content. If network access is unavailable, use the bundled
+references and validate with `plan local check`; run `plan local serve` only
+when the hosted Plan UI is reachable or a local Plan app is already running.
+
+The catalog returns the authoritative, always-current block vocabulary generated
+live from the app's own block registry — the same config the renderer and MDX
+round-trip use — so it can never be stale even if this SKILL.md is an old
+installed copy:
+
+- `get-plan-blocks` (default `format: "reference"`) → a compact table of every
+  block's runtime `type`, exact MDX `<Tag>`, placement, and key data fields.
+  This is your map from each conceptual name above to its real tag and props.
+- `get-plan-blocks` with `format: "schema"` → the full per-block JSON Schema
+  plus a worked example for each block, when you need exact field types,
+  enums, or nesting (e.g. `Diff.annotations`, `Endpoint.params[].in`,
+  `DataModel.entities[].fields[]`).
+
+Author the recap source against the tags and schemas that call returns. The
+complete set of valid block-level tags is whatever `get-plan-blocks` lists;
+any other capitalized tag at the block level is rejected on import with an
+"Unknown plan block" / "did you mean" error. Lowercase HTML tags inside
+`rich-text`/markdown prose (`<div>`, `<span>`, `<code>`, `<br>`, …) are always
+fine — only capitalized component-style block tags are validated.
+
+A few recap-specific authoring rules the registry table cannot encode:
+
+- Every structured block takes a REQUIRED `id` (unique across the whole plan)
+  plus the shared optional `summary` / `editable` envelope. Ordinary top-level
+  Markdown prose imports as rich-text automatically; use `<RichText id="...">`
+  only when prose needs explicit metadata or a preserved referenced block id.
+- Every capitalized block component must be self-closing (`<Diagram ... />`) or
+  explicitly closed around children (`<RichText ...>...</RichText>`). Never
+  leave a bare opening tag like `<RichText ...>` in a paragraph; MDX treats it
+  as unclosed JSX and import fails before the recap can render.
+- Code-bearing blocks (`Code`, `AnnotatedCode`, and `Diff`) are
+  whitespace-sensitive. Prefer the exact MDX form from the `get-plan-blocks`
+  examples / source exporter, where multiline code is encoded as JSON string
+  attributes such as `code={"const x =\n  y"}`. Static template literals are
+  accepted only when they are static strings with no `${...}` interpolation.
+- `Endpoint`: prose `description` is the MDX **children** (body between the
+  tags), not an attribute; for a WebSocket upgrade use `method="GET"`. Each
+  request/response `example` is a JSON **string** (the renderer parses it into
+  the JSON explorer), so keep it a single parseable JSON value.
+- `TabsBlock`: the whole `tabs` array (including nested child blocks) is ONE
+  JSON `tabs={[…]}` prop — there is NO nested `<Tab>` element.
+- `WireframeBlock`: its body is a single `<Screen surface ... html=… />` subtree
+  (nested MDX, not a flat prop); `html` must be a single-quoted string or static
+  template literal, never a dynamic `html={someVar}` expression. See
+  `references/wireframe.md` for the HTML rules.
+- `Diagram`: the whole payload is one `data={{ html?, css?, nodes?, edges?, … }}`
+  attribute and requires either `html` or at least one node; `Mermaid` is its
+  own separate block (`source` text), not a `Diagram` prop.
+
+## Before / After Is The Headline
+
+The recap's center of gravity is the before/after comparison. For document-body
+comparisons there are two primitives, and they cover the whole need together:
+
+- **`columns`** — the side-by-side container, for **structured** comparisons.
+  Use two columns labeled `Before` and `After`, each holding a block (commonly a
+  `data-model`, `api-endpoint`, or `rich-text`), so the reviewer reads the old
+  shape against the new shape in one glance. This is the right primitive for
+  "the schema went from X to Y" or "the endpoint contract changed like this."
+  Do not use `columns` simply to compact or group a list of API endpoints.
+- **`diff`** — for **code**. It renders the literal removed and added lines. Use
+  it for the actual hunks. Use split mode by default for recap code review;
+  reserve `mode: "unified"` for genuinely narrow standalone hunks where
+  side-by-side would hide the code. Key-file diff groups should use horizontal
+  tabs so split diffs get the full document width.
+
+For UI diffs, wireframes are the visual comparison primitive. Use before/after
+wireframes when the comparison clarifies the change; use after-only or a state
+sequence when that better matches the change. The visual headline must show
+exact placement, realistic chrome, and adequate padding before any abstract
+explanation. Do not stop at the first visible affordance when the diff adds a
+flow; show the entry point, the opened surface, and the resulting state or page
+so the reviewer can trace the actual user path. `references/wireframe.md` owns
+the before/after layout choice —
+the `columns` renderer keeps narrow surfaces side by side and auto-stacks wide
+`desktop`/`browser` frames vertically; never hand-build a side-by-side
+wireframe layout in `custom-html`. For document-body
+comparisons, there is no other multi-column primitive — `columns` plus the
+`diff` block are the whole comparison vocabulary. Do not hand-build side-by-side
+layouts in `custom-html`, and do not stack two `data-model` blocks vertically
+and call it a comparison when `columns` exists to put them side by side.
+
+## Grounding Rule
+
+Structured blocks are **true by construction** only if they are derived from the
+actual changed lines. The `diff`, `data-model`, `api-endpoint`, and `file-tree`
+blocks MUST be built mechanically from the real diff — real paths, real fields,
+real method/path, real before/after text — never inferred, rounded, or invented.
+The model writes only the prose: the "why", the narrative, the risk read. A
+confidently wrong recap is dangerous in a review context, because a reviewer who
+trusts the summary may skip the very line the summary got wrong. When the diff
+does not contain a fact, leave it out rather than guess; mark anything the model
+inferred (not extracted) as inferred in prose.
+
+## Security
+
+- **Gate visibility.** Recaps of a private repo are org/login-gated — set the
+  plan's visibility to the owning org or login, never auto-public. A recap can
+  expose unreleased schema, internal endpoints, and architecture; treat it like
+  the source it summarizes. Any PR comment or handoff that links to the recap
+  must say that private-repo recaps require signing in with access to the owning
+  org if the link does not load.
+- **Never transcribe secrets.** A diff can contain API keys, tokens, webhook
+  URLs, signing secrets, `.env` values, or credential-looking literals. Do not
+  copy any of these into a `diff`, `file-tree` snippet, `api-endpoint`, or prose
+  block — redact them (`sk-•••`, `<redacted>`). This mirrors the repo's
+  hardcoded-secret rule: obviously fake placeholders only, never the real value,
+  in any block, caption, or note.
+
+## Bidirectional Loop
+
+In hosted mode, because a recap is a real, editable plan, the same review loop
+as forward plans applies: a reviewer can annotate any block, and the coding
+agent reads `get-plan-feedback` to drive fixes back into the code — annotation →
+agent → diff, the same close-the-loop flow forward plans use. After a reviewer
+annotates a block, call `get-plan-feedback` to read the structured feedback,
+then either update the recap with `create-visual-recap` (passing the existing
+`planId` to replace it in place) or apply targeted changes with
+`update-visual-plan`. The loop is live and wired. In local-files privacy mode,
+do not call those hosted tools; read review notes from chat or local files, edit
+`<plan-dir>/*.mdx` directly, and rerun `plan local check`, `serve`, or `verify`
+for `<plan-dir>`. The one thing not yet automatic is PR-comment-triggered
+re-runs: the GitHub Action creates an initial recap per PR, but it does not yet
+re-run automatically when new review feedback is posted in GitHub — that
+auto-re-run is the remaining fast-follow.
+
+## Related Skills
+
+- **visual-plan** — the canonical command and the source of the shared Wireframe
+  & Canvas and Document Quality cores; a recap follows the same block discipline
+  in reverse.
+- **comment anchors** — recap comments use the same anchor rules as forward
+  plans; see "Interpreting comment anchors" in the visual-plan skill for
+  coordinate frames, wireframe node ids, text-quote resolution, detached
+  threads, routing via `resolutionTarget`, and two-axis consumed/resolved state.
+- **security** — data scoping, secret handling, and the hardcoded-secret rule the
+  recap's redaction and visibility gating mirror.
+- **sharing** — org/login-gated visibility for the plan that holds the recap.
diff --git a/.agents/skills/visual-recap/references/connection.md b/.agents/skills/visual-recap/references/connection.md
new file mode 100644
index 0000000..febff07
--- /dev/null
+++ b/.agents/skills/visual-recap/references/connection.md
@@ -0,0 +1,51 @@
+# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by `/visual-plan` and `/visual-recap`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (`references/local-files.md`) is the one exception.
+
+**The connector is usually the `plan` server**, but older installed agents may
+expose the same hosted connector as `agent-native-plans` — both names are valid,
+so never report the connector as missing just because it is named
+`agent-native-plans` instead of `plan`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (`tool_search` when available) for `create_visual_plan`,
+`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** The usual cause is a connector that did not finish connecting this
+session (it registers zero tools), NOT necessarily an auth problem — so do not
+assume the user must re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+  and start a new Codex session.
+- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same
+  reconnect command with `--client claude-code` and restart Claude.
+
+The same applies when a Plan tool returns `needs auth`, `Unauthorized`, or
+`Session terminated`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. `--client all` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->
diff --git a/.agents/skills/visual-recap/references/local-files.md b/.agents/skills/visual-recap/references/local-files.md
new file mode 100644
index 0000000..cd501ee
--- /dev/null
+++ b/.agents/skills/visual-recap/references/local-files.md
@@ -0,0 +1,99 @@
+# Local-files privacy mode — single source of truth
+
+This file is the canonical contract for fully local, no-database planning and
+recaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it
+in full before using local-files mode; do not call any hosted Plan tool for a
+local plan/recap except the schema-only block-catalog lookup described below.
+
+<!-- SHARED-CORE:local-files START -->
+
+**When to use it.** Use local-files privacy mode when the user explicitly asks
+for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
+files, offline/private work, or repo-owned/source-controlled artifacts, or when
+`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
+policy says the work must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan/recap data must never be sent to the Plan
+MCP server or the Plan app action surface. This is the only exception to the
+always-publish rule in `references/connection.md`.
+
+The local-files contract:
+
+- **Read context locally.** Read source, diff, and stat context from local files
+  and shell commands only. For recaps, the
+  `npx @agent-native/core@latest recap collect-diff`, `scan`, and
+  `build-prompt --local-files` helpers are safe — they operate on local files and
+  do not write to the Plan database.
+- **Fetch the block catalog first** (it sends no plan content). Use the MCP
+  `get-plan-blocks` tool if it is already available, or run
+  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.
+  Use `--format schema` when you need exact nested fields. If network access is
+  unavailable, use the bundled `references/*.md` and rely on `plan local check` to
+  catch invalid tags. Copy the catalog examples verbatim for the fields the
+  registry table cannot encode: `checklist` items need `id` and `label`;
+  `question-form` questions need `id`, `title`, and `mode`, and each option needs
+  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
+  — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
+  (a static template literal is accepted only when it has no `${...}`
+  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green `check` does not guarantee the plan renders.
+  `plan local verify` also stays on-device: it uses the offline lint unless it
+  can reach a Plan renderer on an explicit loopback `--app-url`.
+- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
+  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
+  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
+  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and
+  optional `.plan-state.json`. For a recap, set `kind: "recap"` and
+  `localOnly: true` in the frontmatter/state. Use that exact folder as
+  `<plan-dir>` in every command below.
+- **Check, then serve.** Run
+  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any
+  preview, then
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`
+  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
+  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
+  token file and do not commit it. The URL opens the hosted Plan UI but reads from
+  the localhost bridge on this machine, so it is not shareable across machines.
+  The token is carried in the URL fragment (which is not sent to the hosted
+  origin), and the local-plan route disables DOM autocapture and session replay
+  while retaining sanitized pageviews and error monitoring. On
+  macOS `--open` prefers Chromium browsers; if Safari opens, switch to
+  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
+  HTTP localhost bridge. If the Plan app itself is running locally with the same
+  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly
+  offline environment, hand off the `<plan-dir>` path after `plan local check` and
+  note that interactive preview requires network access to the hosted Plan UI or a
+  running local Plan app.
+- **Headless verify.** Run
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
+  It starts the bridge and checks the private-network preflight and JSON payload
+  entirely on loopback. It never sends MDX or assets to a remote validation
+  action. When `--app-url` points to a loopback Plan app, verify also validates
+  against that local app's real renderer schema via `validate-local-plan-source`.
+  A non-`ok` result with
+  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
+  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
+  is `false`, verify used the offline lint because the app URL was remote or the
+  local Plan app was unavailable. Run a local Plan app and pass
+  `--app-url http://localhost:8096` for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
+  concrete validation error.
+- **Never call hosted tools for that plan/recap.** Do not call
+  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
+  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,
+  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,
+  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any
+  other hosted Plan tool — except the schema-only block-catalog lookup above.
+- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
+  `plan local check`, and rerun `serve` or `verify` when that preview path is
+  available. Summarize the new local URL when one exists; otherwise summarize the
+  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage
+  attachment, and publish/export receipts are unavailable until the user
+  explicitly opts into publishing.
+
+Local-files mode prevents plan/recap content from being uploaded to the
+Agent-Native Plan server or database. It does not by itself make the coding agent's language model local;
+for that stronger boundary the host agent/model must also be local or otherwise
+approved by the user.
+
+<!-- SHARED-CORE:local-files END -->
diff --git a/.agents/skills/visual-recap/references/wireframe.md b/.agents/skills/visual-recap/references/wireframe.md
new file mode 100644
index 0000000..08ea41a
--- /dev/null
+++ b/.agents/skills/visual-recap/references/wireframe.md
@@ -0,0 +1,312 @@
+# 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.
+
+<!-- SHARED-CORE:wireframe-quality START -->
+
+**A wireframe is an HTML mockup. The renderer owns the look; you write the
+content.** Set `data.html` to a self-contained, semantic HTML fragment of the
+screen and set `data.surface`. The renderer owns the surface footprint/aspect,
+the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
+never write `<html>`/`<body>`/`<script>`/`<style>` tags or any
+width/height/coordinates. You write real HTML layout and real product
+content; the renderer styles and roughens it.
+
+**A wireframe block's data is an HTML screen plus a surface:**
+
+```json
+{
+  "surface": "browser",
+  "html": "<div style=\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\"><h1>Sign in</h1><p class=\"wf-muted\">Use your work email to continue.</p><div class=\"wf-card\" style=\"display:flex;flex-direction:column;gap:10px\"><label>Email<input value=\"jane@acme.co\" /></label><label>Password<input value=\"••••••••\" /></label><label style=\"display:flex;align-items:center;gap:8px\"><input type=\"checkbox\" checked /> Remember me</label><button class=\"primary\">Sign in</button></div><a href=\"#\">Forgot password?</a></div>"
+}
+```
+
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type="checkbox">`, `a`, `hr`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- `.wf-card` / `.wf-box` — a bordered, padded container (a panel, a list item).
+- `.wf-pill` / `.wf-chip` — a rounded tag or filter; add `.accent`
+  (`<span class="wf-pill accent">`) for the accent-filled variant.
+- `.wf-muted` — secondary/muted text (or use `<small>`).
+- `button.primary` or any element with `[data-primary]` — the accent-filled
+  primary button.
+
+**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:
+drop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a
+wireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.
+Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
+and annotations for separation. Only show a shadow when the real product UI
+already has that shadow and it is essential to the change being reviewed.
+
+**Use renderer icons, not visible icon words.** For icon-only buttons or leading
+icons inside fields, chips, menu items, and toolbars, write an empty marker such
+as `<span data-icon="mail" aria-label="Email"></span>` or
+`<i data-icon="lock"></i>`. The renderer replaces it with a Tabler-style SVG and
+the `.wf-icon` class sizes it to the surrounding text. Supported names and
+aliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,
+`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,
+`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,
+`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words
+like "email", "lock", "search", "chevron", or "more" where the product UI would
+show an icon; use text only when it is a real label a user would read.
+
+**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+`style="border:1.4px solid var(--wf-line)"`. The tokens are `--wf-ink` (text),
+`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`
+(page background), `--wf-card` (container surface), `--wf-accent` /
+`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,
+and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
+renderer owns the sketch/clean font.
+
+**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
+`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,
+`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,
+or arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the
+mockup and can make dark-mode canvas frames unreadable. Use bare semantic
+elements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before
+publishing, scan every wireframe `class` and `style` attribute: if a class sets
+background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
+or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
+are still discouraged; inline flex/grid styles are safer and easier to review.
+
+**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
+`.wf-*` primitives, controls, and inline border dividers by default. Do not add
+`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or
+nested containers unless that single container is the visual point. Use
+`data-rough` only for a deliberate one-off shape. If a mockup starts looking
+like stacked/overlapping sketch lines, remove rough targets from parent
+containers and let backgrounds plus spacing separate the surfaces.
+
+**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.
+
+**Lay out with inline `style` flex/grid.** You write the real layout —
+`display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
+
+**Surface presets — match the real footprint, never default to desktop+mobile.**
+Pick the `surface` that matches what the user will actually see:
+
+- `browser`: a web page that needs a browser chrome frame around it.
+- `desktop`: a full desktop app page or app shell.
+- `mobile`: a phone screen, only when the work is genuinely mobile.
+- `popover`: a small floating menu, dropdown, or inline popover.
+- `panel`: a side panel, inspector, or sidebar widget.
+
+A sidebar popover renders as a small surface, not a desktop page and a phone
+frame. Do not emit `desktop` + `mobile` variants unless responsive behavior
+actually changes the layout. For a component or widget, show one broader
+app-context frame only when placement affects understanding, then the focused
+component states.
+
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve `diagram` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use `surface: "popover"` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching `panel` / `desktop` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell. Inspect the
+actual app components before drawing an existing product: sidebar density,
+toolbar actions, overflow menus, property panels, and framework chrome should
+match the product unless the plan intentionally changes them.
+
+**Keep product screens pure.** A product wireframe shows the app state a user
+would actually see. Do not embed file contracts, architecture arrows, repo pills,
+mode explanations, or implementation callouts inside the screen just to explain
+the plan. Put those in canvas annotations, a separate diagram, or the document
+body. Secondary UI such as properties, history, sync, export, or agent controls
+should appear where the real product would put them: an overflow popover, sheet,
+panel, or separate framework sidebar state, not a generic permanent right
+inspector unless that inspector is the actual design.
+
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose `html` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+`surface` (e.g. `popover`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and
+fill the `html` with neutral, textless placeholder geometry — boxes and bars
+built as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a `custom-html` document block
+to fake a loader.
+
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]`. Each `find` is a unique snippet of the current html (read it
+first with `get-visual-plan`); set `all: true` on an edit to replace every
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
+
+**Choose the outer frame deliberately.** Wireframe and diagram data accept
+`frame: "auto" | "show" | "hide"` in block data (`<Screen frame="hide">` in
+MDX wireframes, `<Diagram frame="hide">` for MDX diagrams). Leave it unset or
+`auto` when the host context should decide: Plan and recap surfaces default to a
+drawn outer frame; docs surfaces default to no outer frame. Use `show` for
+standalone product screens, before/after recap comparisons, screenshot-like
+artifacts, and visuals that need containment from surrounding prose. Use `hide`
+when a docs page, tab, column, card, canvas artboard, or the visual's own
+internal chrome already supplies the boundary. Do not use `hide` to compensate
+for cramped content; fix the layout instead.
+
+**Inner padding and borders still matter.** Always wrap HTML wireframe content
+in a root container with real inner padding before drawing cards, fields, pills,
+labels, or controls. Use at least 14-16px of padding, `box-sizing: border-box`,
+`height: 100%`, and `gap` between child rows on the root node itself so the
+first row never sits flush against the screen edge. Do not rely on padding on a
+nested page section as the first visible inset; the outermost element must
+create the breathing room. Keep text away from borders: every container, field,
+button, menu item, and annotation needs enough padding and line-height to read
+cleanly in the rendered Plan view.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
+
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+
+**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
+breadcrumbs, chip/filter rows, branch and file names, file chips, and code
+filenames — any deliberately single-line row — do not let long text wrap. Put
+`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`
+on the individual labels that can grow), so the wireframe demonstrates the actual
+layout behavior instead of producing ugly stacked or vertical text. Use
+horizontally scrollable or clipped rails for overflow.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Persistent chrome bars span the full frame width.** Top bars, app headers,
+toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
+Lay each one out as a single flex row that fills the frame
+(`style="display:flex;align-items:center;width:100%"`) and push trailing actions
+to the right edge with a flex spacer (`<div style="flex:1"></div>`) between the
+leading group and the trailing group — never center a bar inside a narrow,
+centered block, and never let it collapse to the width of its contents. In a
+Before/After pair the bar stays full-width in BOTH states even when one state has
+fewer controls; the spacer absorbs the difference so the remaining controls hold
+their edge alignment instead of sliding to the center.
+
+**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
+any persistent bottom action row, make the frame itself a flex column at
+`height:100%` (`style="display:flex;flex-direction:column;height:100%"`), give the
+scrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST
+child of the frame (or set `margin-top:auto` on it). The bar then sits flush at
+the bottom of the surface instead of floating directly under the content with an
+empty band beneath it.
+
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new `Edit with AI` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half.
+
+**Name the states with the column header, never inside the frame.** For
+document-body wireframes (recaps), put the two
+states in a `columns` block and set each column's `label` to `Before` and
+`After` — the renderer draws that label as an `h4` heading above each frame. Do
+NOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a
+label placed inside reads as part of the product UI, lands in a random corner,
+and clutters the comparison. The column header is the one and only place the
+state name belongs. On a canvas, place the two state artboards as neighbors with
+frame labels — never encode Before/After inside the html.
+
+**Let the surface choose side-by-side vs. stacked.** For document-body
+wireframes (recaps), the `columns` renderer lays
+narrow surfaces (`mobile`, `popover`, `panel`) out side by side, and
+automatically stacks wide surfaces (`desktop`, `browser`) vertically at full
+document width so a large frame is never crushed into a half-width column and
+cropped. Author both wireframes with the real `surface` and the matching
+`Before`/`After` column labels; do not hand-stack the pair into separate
+top-level wireframes or duplicate the state name as body content.
+
+**Good example — a contacts list, surface `browser`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+```html
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+```
+
+<!-- SHARED-CORE:wireframe-quality END -->
diff --git a/skills-lock.json b/skills-lock.json
index 02f85a7..8f15828 100644
--- a/skills-lock.json
+++ b/skills-lock.json
@@ -42,6 +42,12 @@
       "sourceType": "github",
       "skillPath": "skills/react-best-practices/SKILL.md",
       "computedHash": "ca7b0c0c6e5f2750043f7f0cd72d16ac4e2abc48f9b5500d047a4b77a2506212"
+    },
+    "visual-recap": {
+      "source": "builderio/skills",
+      "sourceType": "github",
+      "skillPath": "skills/visual-recap/SKILL.md",
+      "computedHash": "de5c354d3fd6fcd2b10ef99f0c48872bab7814dfcee01fe01bc1e68d22c2c668"
     }
   }
 }