visual-recap

## Installed Mode Default storage for this installation: local files. Create and update plans and recaps as MDX folders under `plans/<slug>/` when they should be checked in, or under a repo-ignored/temp folder when they should stay private scratch. Before authoring structured MDX, run `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read the no-auth block catalog; it sends no plan content. Then run `npx @agent-native/core@latest plan local check --dir plans/<slug>`, then `npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan|recap --open`, and report the local bridge URL from stdout or `plans/<slug>/.plan-url`. Treat `.plan-url` as a local token file and do not commit it. It opens the hosted Plan UI but reads from the localhost bridge on this machine, so it is not shareable across machines. On macOS, use Chrome/Chromium if Safari blocks the localhost bridge; run `plan local verify --dir plans/<slug> --kind plan|recap` for headless diagnostics. No sharing, all local. Use a hosted or self-hosted Plan MCP connector only if the user explicitly asks to publish or share. # 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. ## Local-Files Privacy Mode Exception Use local-files privacy mode when the user explicitly asks for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local files, offline/private recaps, or when `AGENT_NATIVE_PLANS_MODE=local-files` is set. This is the only exception to the hosted publish rule below. In local-files mode: - Read the diff/stat/source context from local files and shell commands only. The existing `npx @agent-native/core@latest recap collect-diff`, `scan`, and `build-prompt --local-files` helpers are safe to use because they operate on local files and do not write to the Plan database. - Fetch/read the block catalog before writing structured MDX. Use `npx @agent-native/core@latest plan blocks --out plan-blocks.md` when the Plan MCP connector is not registered; it calls the public no-auth `get-plan-blocks` route and sends no recap content. If network access is unavailable, use the bundled references and validate the MDX with `plan local check`; do not run `plan local serve` unless the hosted Plan UI is reachable or a local Plan app is already running. For `checklist` and `question-form`, copy the catalog examples verbatim: checklist items need `id` and `label`; question-form questions need `id`, `title`, and `mode`; and each option needs `id` and `label`. `plan local check` validates these required fields against the renderer schema. - Write the recap as a local MDX folder: use `plans/<slug>/` when the user wants the artifact checked into the repo, or use a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The folder contains `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Set `kind: "recap"` and `localOnly: true` in frontmatter/state when authoring the source. Use that exact chosen folder as `<plan-dir>` in every local CLI command below. - Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any preview. When the hosted Plan UI is reachable, run `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open`. Report the returned local bridge URL from stdout or `<plan-dir>/.plan-url`. Treat `.plan-url` as a local token file and do not commit it. The URL opens the hosted Plan UI but reads from the localhost bridge on this machine, so it is not shareable across machines. On macOS, `--open` prefers Chromium browsers; if Safari opens, switch to Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the HTTP localhost bridge. If the Plan app itself is running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly offline environment, hand off the local `<plan-dir>` path after `plan local check` and note that interactive preview requires either network access to the hosted Plan UI or a running local Plan app. - For headless verification, run `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind recap`. It starts the bridge, checks the private-network preflight and JSON payload, prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the concrete validation error. - Do **not** call `create-visual-recap`, `create-visual-plan`, `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`, `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any hosted Plan tool for that recap except the schema-only block catalog lookup above. - Treat review feedback as file or chat feedback: update the MDX files directly, rerun `plan local check`, and rerun `serve` or `verify` only when that preview path is available. Summarize the new local URL when one exists; otherwise summarize the checked local folder path. Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment publishing are unavailable until the user explicitly opts into publishing. Local-files mode prevents recap content from going to the Agent-Native Plan database. It does not by itself make the coding agent's language model local; for that stronger privacy boundary, the host agent/model must also be local or otherwise approved by the user. ## Always Publish As An Agent-Native Plan — Never Inline The deliverable is ALWAYS a published Agent-Native Plan, created with the `create-visual-recap` tool on the Plan MCP connector. The connector is usually exposed as the `plan` server, but older installed agents may expose the same hosted connector as `agent-native-plans`; both names are valid. NEVER hand the recap to the user as inline chat content — not Markdown prose, not an ASCII sketch, not a table, not a fenced "wireframe", not a "here's the recap" summary. A recap's entire value is the hosted, interactive, annotatable plan; an inline summary is not a recap, it is the thing a recap replaces. The only supported output is to publish the plan and return its absolute URL. Some clients lazy-load connector tools through a deferred tool registry instead of showing the `plan` namespace upfront. Before declaring the Plan connector missing, search/load tools with the host's discovery surface (`tool_search` when available) for `create_visual_recap`, `create_visual_plan`, or `get_plan_blocks`, then use the Plan MCP tools it exposes. Except for the explicit local-files privacy mode above, if neither the `plan` nor legacy `agent-native-plans` Plan MCP tools are available after deferred tool discovery, do NOT improvise an inline recap as a fallback. Do not report the connector as disconnected just because it is named `agent-native-plans` instead of `plan`, or because the tools were not visible before discovery. The usual cause is a connector that did not finish connecting this session (it registers zero tools), NOT necessarily an auth problem — so do not assume the user must authenticate. Stop and tell the user how to restore it for their current client: in Codex/Codex Desktop, run `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` and start a new Codex session; in Claude Code, run `/mcp` and choose Authenticate/Reconnect, or run the reconnect command with `--client claude-code` and restart Claude. Auth is stored per client config/session; `--client all` refreshes every local client config that already has the Plan entry, but each running client still has to reload its MCP tools. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by URL regardless of connector name. Never reinstall from scratch just to fix auth. Then publish once the tool is reachable. Falling back to inline content is a defect, not a degraded mode. ## When To Use Build a recap when a PR or commit is large, multi-file, or touches schema, API contracts, or architecture, and a reviewer would benefit from seeing the change mapped to structured blocks before reading the raw diff. A GitHub Action can generate one automatically from a PR diff; an agent can generate one on request ("recap this PR", "show me what this branch changed"). Skip it for small, single-file, or obvious diffs — a recap is review overhead, and a tiny change reviews faster as plain diff. ## Recap The Whole Work Unit When `/visual-recap` is invoked in a chat thread after work has already happened, the default scope is the whole current work unit/thread, not only the most recent user message, tool action, or follow-up fix. Gather the thread-owned changes across the conversation: original implementation work, later bug fixes, UI follow-ups, tests, changesets, skill/instruction updates, generated plan/source artifacts, and any local import/linking fixes needed to make the recap open. Use the current diff plus conversation context to separate thread-owned changes from unrelated dirty work that existed before the thread. Exclude unrelated pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred, state the assumption or ask a concise question before publishing. When updating an existing recap after feedback, revise the recap so it still covers the whole thread/work unit plus the new correction. Do not replace a broad recap with a narrow recap of only the latest feedback unless the user explicitly asks for that narrower scope. ## Keep The Recap Body Lean Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to the generated plan body. In particular, do not create a `rich-text` block just to say the recap is an aid, that the reviewer should still review the diff, how many files changed, or which ref/working tree generated the recap. The plan title, brief, and `file-tree` (which carries the per-file change stats) already carry that context. Only add prose blocks when they tell the reviewer something specific about the change that the structured blocks do not: the objective, a real compatibility risk, an important decision visible in the diff, or a grounded review note. ## Recaps Must Be Substantial Lean is not the same as thin. A recap is not a single wireframe plus one sentence — that under-serves the reviewer as much as boilerplate prose over-serves them. Alongside the visual/structural headline (wireframes, `data-model`, `api-endpoint`, `diagram`), a substantial recap also carries the implementation evidence: - A short surface/state inventory before authoring: list the changed routes, components, popovers/dialogs, role/access states, empty/error states, and shared abstractions visible in the diff. The final recap must either represent each meaningful item with a block or intentionally omit it because it is tiny, redundant, or not user-visible. - A `file-tree` of the changed files with each entry's `change` flag, so the reviewer sees the footprint of the work at a glance. - The split `diff` of the KEY changed files, grouped under a `## Key changes` `rich-text` heading in a single horizontal `tabs` block (the default orientation, one file per tab), with a one-line `summary` and a few `annotations` on each — so the reviewer can drop from the high-altitude shape straight into the load-bearing code. Use horizontal file tabs, not a vertical side rail, so the selected file has enough width for the side-by-side diff. Skip the diff appendix only for a genuinely tiny change that reviews faster as plain diff (see "When To Use"); for any change worth recapping, the file-tree and key-change diffs belong in the plan. ## Canonical Shape And Budgets A strong recap follows one skeleton, top to bottom: 1. UI-impact headline — wireframes first, when the diff changed rendered UI. 2. Short outcome narrative (`rich-text`): what changed and why, 1-3 paragraphs. 3. `data-model` / `api-endpoint` blocks for schema and contract changes. 4. `file-tree` of the changed files with `change` flags. 5. `## Key changes` — one horizontal `tabs` block of `diff` / `annotated-code`. Budgets that keep the recap reviewable: - 3-8 key-change tabs. Fewer than 3 on a large change under-serves the reviewer; more than 8 stops being a summary. - Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per tab; summarize or link the rest of a long file instead of dumping it. - Title at most ~70 characters; brief 1-3 sentences. **GOOD.** A 25-file auth change: Before/After wireframes of the login surface, a two-paragraph narrative, a diff-aware `data-model` of the sessions table, an `api-endpoint` for the new refresh route, a `file-tree` with change flags, and `## Key changes` with five focused tabs, each with a one-line `summary` and a few annotations on the load-bearing hunks. **BAD.** One giant unsegmented diff dump with no summaries or annotations; or a sparse three-block recap of a 40-file change (one wireframe, one sentence, one file list) that forces the reviewer back into the raw diff anyway. ## UI Impact Needs Wireframes When the diff changes rendered UI, layout, density, visual state, interaction affordances, navigation, controls, menus, dialogs, or design tokens, the recap MUST include one or more wireframes. Prose and file diffs are not a substitute for showing what changed visually. Before choosing wireframes, make a UI coverage pass from the diff: - Identify the entry surface where the change appears, such as a page header, list row, toolbar, route shell, or menu trigger. - Identify the interaction surface that opens or changes, such as a popover, dialog, tab, sheet, dropdown, inline editor, or toast. - Identify the resulting destination or persistent state, such as a public page, read-only view, empty state, error state, loading state, permission-denied state, or saved/shared state. - Identify access or role variants when permissions change. Owner/admin/editor versus viewer/non-manager differences are visual behavior and need a compact matrix, paired wireframes, or clearly labeled state sequence. For UI-heavy PRs, a single before/after of the entry surface is not enough. Show the changed entry point, the main changed interaction surface, and the resulting/destination state. Add more states when the diff adds tabs, role-based controls, public/private visibility, invite/manage flows, destructive controls, or empty/error branches. Choose the smallest visual surface that makes the review clear: - Use a `Before` / `After` wireframe pair when the reviewer benefits from direct comparison, such as a removed or added control, a changed state, layout density, ordering, navigation, or a visible component replacement. `references/wireframe.md` owns how to lay that pair out (columns vs. vertical stack by geometry). - Use an after-only wireframe when the change is purely additive or the "before" state would only show absence without adding review value. - Use more than two wireframes when the UI change is flow-dependent, responsive, or stateful; show the meaningful states in order instead of forcing a single before/after pair. - For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the matching `surface` (`popover`, `panel`, etc.) and show the focused sub-surface. Do not redraw a full page unless placement in the page is itself part of the change. Ground each wireframe in the changed UI behavior, component names, file paths, and diff-visible labels/states. If exact pixels are inferred rather than captured, say so in the wireframe caption or a concise annotation. For local/manual recaps, import or update the plan source that holds the wireframes so the rendered recap opens with the UI visual available. ## Wireframe Quality — read `references/wireframe.md` UI recap/plan wireframes must meet a strict quality bar — full-width chrome, pinned bottom bars, real product content, before/after comparability, the right `surface` preset, `--wf-*` tokens instead of hex, and no `<html>`/`<style>`/font tags. Before authoring ANY wireframe / `<Screen>` / `WireframeBlock`, READ `references/wireframe.md` in this skill directory — it is the single source of truth for HTML wireframe quality, shared word for word with `/visual-plan` and `/visual-recap`. Do not author wireframes from memory. Use the standard `WireframeBlock` / `<Screen>` format so the Plan viewer owns the surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate when placement precision matters, especially popovers, menus, dialogs, and dense forms. For HTML wireframes, keep `renderMode` unset or `wireframe` unless a design-only editable mockup is explicitly required, because `renderMode="design"` disables the sketchy rough overlay. When a browser tool is available, render a UI-impact recap in the Plan viewer and visually inspect it at the current theme before sharing. If any label, annotation, toolbar, or wireframe content overlaps another element, fix the MDX and re-import before reporting the link. A text-match screenshot is not enough; visually inspect the captured image. When no browser is available (for example a headless CI agent), state that in the recap handoff instead. ## Top Canvas Recaps — read `../visual-plan/references/canvas.md` When a recap includes a top canvas, storyboard, or flow view, READ `../visual-plan/references/canvas.md` before authoring `canvas.mdx`. Recap canvas artboards must use the same HTML wireframe path as good document-body wireframes: `<Screen surface="..." html={...} />` with a semantic HTML fragment. Do not author fresh kit-tree children such as `<FrameScreen>`, `<Card>`, `<Row>`, `<Title>`, or `<Btn>` inside canvas `<Screen>` tags. Those components are legacy compatibility markup for old plans; in new canvas storyboards they can produce cramped or overlapping layouts even when the inline body wireframe looks good. If a canvas mockup looks worse than the same screen below the fold, assume it used the legacy kit path and replace it with an HTML screen. ## Open And Report The Recap In local-files privacy mode, run `plan local check` first, then report the local bridge URL from `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open` or from `<plan-dir>/.plan-url`. It opens the hosted Plan UI but reads from the localhost bridge on this machine, so it is not shareable across machines. If the Plan app itself is running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. Do not invent a hosted database URL and do not publish just to get an absolute Plan link. After creating the recap, link the reviewer to the rendered plan with an **absolute URL on the origin whose database actually holds the plan**. That origin is the Plan MCP server you just created the recap through — NOT whatever dev server you happen to know is running. The create tool returns the correct link; report THAT. Never make the primary link a local `plan.mdx` file, a local mirror folder, or a relative path such as `/plans/<id>`. When the recap is posted to a PR for a private repo, the plan link is not a public URL. Make the PR comment/handoff copy explicit: reviewers may need to sign in to Agent-Native Plans with an account that has access to the owning organization before the link loads. Use wording like: "Private repo recap: sign in with access to this org if the plan does not open." Do not imply the link is broken or public when access is gated by repo/org visibility. A recap lives only in the database of the MCP that created it. A separately running local dev server (e.g. `http://localhost:8081`) has its OWN database and will NOT contain a recap created through the hosted MCP, so a hand-built `localhost` link returns "Plan not found". This is the most common recap mistake — do not guess an origin you have not confirmed shares the MCP's data. Resolve the URL in this order: 1. Use the absolute URL the create tool RETURNS — `openLink.webUrl`, else the `visualUrl` in the returned `plan.mdx` frontmatter, else `url`/`path` resolved against the MCP server's own origin (for the hosted MCP that is `https://plan.agent-native.com`). This always points at the database that has the plan. 2. Use a `localhost`/dev origin ONLY when the recap was created through a Plan MCP bound to that same origin — i.e. that MCP's url is `http://localhost:<port>/_agent-native/mcp`. Creating through the hosted MCP and linking to localhost is the exact mismatch that 404s. 3. If only a plan id is available, build the MCP origin's absolute URL (hosted: `https://plan.agent-native.com/plans/<id>`) and say it was inferred. If the user wants to review on localhost but the recap was created through the hosted MCP, say so plainly: the local dev server cannot see it. To view a recap on localhost (e.g. to exercise un-deployed local renderer changes), they must connect a LOCAL Plan MCP (`http://localhost:<port>/_agent-native/mcp`) and re-create the recap through it so it lands in the app's PostgreSQL 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