@agent-native/core 0.44.3 → 0.45.0

package/dist/cli/skills.js

@@ -814,6 +814,37 @@ plan needs a richer review surface.
   update the plan with \`update-visual-plan\` rather than only changing course in
   chat, and re-read the approved plan before major steps.
 
+## Local-Files Privacy Mode
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+planning, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. In this mode the
+plan data must never be sent to the Plan MCP server or Plan app action surface.
+
+The local-files contract is:
+
+- Read source context from local files and shell commands only.
+- Write the plan as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
+  \`.plan-state.json\`.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind plan\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- Do **not** call \`create-visual-plan\`, \`create-ui-plan\`,
+  \`create-prototype-plan\`, \`create-plan-design\`, \`import-visual-plan-source\`,
+  \`update-visual-plan\`, \`patch-visual-plan-source\`, \`get-plan-feedback\`,
+  \`export-visual-plan\`, or any hosted Plan tool for that plan.
+- Treat feedback as file or chat feedback: update the MDX files directly, rerun
+  the local preview command, and summarize the new local URL/path. Hosted
+  comments, sharing, history, and publish/export receipts are unavailable until
+  the user explicitly opts into publishing.
+
+Local-files mode prevents plan content from going to the Agent-Native Plan
+database. It does not by itself make the coding agent's language model local;
+for that stronger privacy boundary, the host agent/model must also be local or
+otherwise approved by the user.
+
 ## Core Workflow
 
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
@@ -1466,6 +1497,41 @@ schema, API, file, and architecture changes become the same \`data-model\`,
 now they summarize work that exists. A reviewer scans the shape of the change
 before spending attention on the literal lines.
 
+## Local-Files Privacy Mode Exception
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+recaps, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. This is the only
+exception to the hosted publish rule below.
+
+In local-files mode:
+
+- Read the diff/stat/source context from local files and shell commands only.
+  The existing \`agent-native recap collect-diff\`, \`scan\`, and
+  \`build-prompt --local-files\` helpers are safe to use because they operate on
+  local files and do not write to the Plan database.
+- Write the recap as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
+  \`.plan-state.json\`. Set \`kind: "recap"\` and \`localOnly: true\` in
+  frontmatter/state when authoring the source.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind recap\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- Do **not** call \`create-visual-recap\`, \`create-visual-plan\`,
+  \`import-visual-plan-source\`, \`update-visual-plan\`,
+  \`patch-visual-plan-source\`, \`get-plan-feedback\`, \`export-visual-plan\`,
+  \`set-resource-visibility\`, or any hosted Plan tool for that recap.
+- Treat review feedback as file or chat feedback: update the MDX files directly,
+  rerun the local preview command, and summarize the new local URL/path.
+  Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
+  publishing are unavailable until the user explicitly opts into publishing.
+
+Local-files mode prevents recap content from going to the Agent-Native Plan
+database. It does not by itself make the coding agent's language model local;
+for that stronger privacy boundary, the host agent/model must also be local or
+otherwise approved by the user.
+
 ## Always Publish As An Agent-Native Plan — Never Inline
 
 The deliverable is ALWAYS a published Agent-Native Plan, created with the
@@ -1476,7 +1542,8 @@ entire value is the hosted, interactive, annotatable plan; an inline summary is
 not a recap, it is the thing a recap replaces. The only supported output is to
 publish the plan and return its absolute URL.
 
-If the \`plan\` MCP server's tools are not available, do NOT improvise an inline
+Except for the explicit local-files privacy mode above, if the \`plan\` MCP
+server's tools are not available, do NOT improvise an inline
 recap as a fallback. The usual cause is a connector that did not finish
 connecting this session (it registers zero tools), NOT necessarily an auth
 problem — so do not assume the user must authenticate. Stop and tell the user
@@ -1538,10 +1605,11 @@ evidence:
 - 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 vertical \`tabs\` block (file labels as the left
-  rail), with a one-line \`summary\` and a few \`annotations\` on each — so the
-  reviewer can drop from the high-altitude shape straight into the load-bearing
-  code.
+  \`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
@@ -1585,7 +1653,226 @@ architecture boxes. The following bar is shared, word for word, with
 wireframe quality, and applies to a recap's standalone \`wireframe\` /
 \`WireframeBlock\` / \`<Screen>\` exactly as it applies to a plan's canvas artboard.
 
-${WIREFRAME_QUALITY_CORE}
+<!-- SHARED-CORE:wireframe-quality START -->
+
+**A wireframe is an HTML mockup. The renderer owns the look; you write the
+content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
+screen and set \`data.surface\`. The renderer owns the surface footprint/aspect,
+the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
+never write \`<html>\`/\`<body>\`/\`<script>\`/\`<style>\` tags, font-family, hex colors,
+or any width/height/coordinates. You write real HTML layout and real product
+content; the renderer styles and roughens it.
+
+**A wireframe block's data is an HTML screen plus a surface:**
+
+\`\`\`json
+{
+  "surface": "browser",
+  "html": "<div style=\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\"><h1>Sign in</h1><p class=\\"wf-muted\\">Use your work email to continue.</p><div class=\\"wf-card\\" style=\\"display:flex;flex-direction:column;gap:10px\\"><label>Email<input value=\\"jane@acme.co\\" /></label><label>Password<input value=\\"••••••••\\" /></label><label style=\\"display:flex;align-items:center;gap:8px\\"><input type=\\"checkbox\\" checked /> Remember me</label><button class=\\"primary\\">Sign in</button></div><a href=\\"#\\">Forgot password?</a></div>"
+}
+\`\`\`
+
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
+- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
+  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
+- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
+- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
+  primary button.
+
+**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
+\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
+(page background), \`--wf-card\` (raised surface), \`--wf-accent\` /
+\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
+and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
+renderer owns the sketch/clean font.
+
+**Lay out with inline \`style\` flex/grid.** You write the real layout —
+\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
+
+**Surface presets — match the real footprint, never default to desktop+mobile.**
+Pick the \`surface\` that matches what the user will actually see:
+
+- \`browser\`: a web page that needs a browser chrome frame around it.
+- \`desktop\`: a full desktop app page or app shell.
+- \`mobile\`: a phone screen, only when the work is genuinely mobile.
+- \`popover\`: a small floating menu, dropdown, or inline popover.
+- \`panel\`: a side panel, inspector, or sidebar widget.
+
+A sidebar popover renders as a small surface, not a desktop page and a phone
+frame. Do not emit \`desktop\` + \`mobile\` variants unless responsive behavior
+actually changes the layout. For a component or widget, show one broader
+app-context frame only when placement affects understanding, then the focused
+component states.
+
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve \`diagram\` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use \`surface: "popover"\` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching \`panel\` / \`desktop\` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell.
+
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
+fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
+built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a \`custom-html\` document block
+to fake a loader.
+
+**Editing an existing mockup.** To change one element, text, or color in an
+existing html mockup, do NOT regenerate the frame — call \`update-visual-plan\`
+with \`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
+first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
+occurrence. The result is re-sanitized.
+
+**Treat the wireframe border as part of the visible design.** Always wrap HTML
+wireframe content in a root container with real inner padding before drawing
+cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
+\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows so the
+first row never sits flush against the screen border. Keep text away from
+borders: every container, field, button, menu item, and annotation needs enough
+padding and line-height to read cleanly in the rendered Plan view.
+
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+\`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+
+**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
+breadcrumbs, chip/filter rows, branch and file names, file chips, and code
+filenames — any deliberately single-line row — do not let long text wrap. Put
+\`white-space: nowrap\` on the row (and \`overflow: hidden; text-overflow: ellipsis\`
+on the individual labels that can grow), so the wireframe demonstrates the actual
+layout behavior instead of producing ugly stacked or vertical text. Use
+horizontally scrollable or clipped rails for overflow.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Persistent chrome bars span the full frame width.** Top bars, app headers,
+toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
+Lay each one out as a single flex row that fills the frame
+(\`style="display:flex;align-items:center;width:100%"\`) and push trailing actions
+to the right edge with a flex spacer (\`<div style="flex:1"></div>\`) between the
+leading group and the trailing group — never center a bar inside a narrow,
+centered block, and never let it collapse to the width of its contents. In a
+Before/After pair the bar stays full-width in BOTH states even when one state has
+fewer controls; the spacer absorbs the difference so the remaining controls hold
+their edge alignment instead of sliding to the center.
+
+**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
+any persistent bottom action row, make the frame itself a flex column at
+\`height:100%\` (\`style="display:flex;flex-direction:column;height:100%"\`), give the
+scrolling body \`flex:1\` so it absorbs the slack, and place the bar as the LAST
+child of the frame (or set \`margin-top:auto\` on it). The bar then sits flush at
+the bottom of the surface instead of floating directly under the content with an
+empty band beneath it.
+
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new \`Edit with AI\` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half.
+
+**Name the states with the column header, never inside the frame.** Put the two
+states in a \`columns\` block and set each column's \`label\` to \`Before\` and
+\`After\` — the renderer draws that label as an \`h4\` heading above each frame. Do
+NOT bake a \`Before\`/\`After\` pill, title, or heading into the wireframe \`html\`: a
+label placed inside reads as part of the product UI, lands in a random corner,
+and clutters the comparison. The column header is the one and only place the
+state name belongs.
+
+**Let the surface choose side-by-side vs. stacked.** The \`columns\` renderer lays
+narrow surfaces (\`mobile\`, \`popover\`, \`panel\`) out side by side, and
+automatically stacks wide surfaces (\`desktop\`, \`browser\`) vertically at full
+document width so a large frame is never crushed into a half-width column and
+cropped. Author both wireframes with the real \`surface\` and the matching
+\`Before\`/\`After\` column labels; do not hand-stack the pair into separate
+top-level wireframes or duplicate the state name as body content.
+
+**Good example — a contacts list, surface \`browser\`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+\`\`\`html
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+\`\`\`
+
+<!-- SHARED-CORE:wireframe-quality END -->
 
 Use the standard \`WireframeBlock\` / \`<Screen>\` format so the Plan viewer owns the
 surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate
@@ -1602,6 +1889,11 @@ text-match screenshot is not enough; visually inspect the captured image.
 
 ## Open And Report The Recap
 
+In local-files privacy mode, report the local preview URL/path from
+\`agent-native plan local preview\` or the \`/local-plans/<slug>\` route for a local
+Plan app using the same \`PLAN_LOCAL_DIR\`. Do not invent a hosted URL and do not
+publish just to get an absolute Plan link.
+
 After creating the recap, link the reviewer to the rendered plan with an
 **absolute URL on the origin whose database actually holds the plan**. That
 origin is the Plan MCP server you just created the recap through — NOT whatever
@@ -1645,7 +1937,9 @@ artifacts, not as the main way to open the recap.
 ## Diff → Block Mapping
 
 Map each kind of change to the block that carries it, derived mechanically from
-the actual diff:
+the actual diff. The names below are the CONCEPTUAL block types, not the JSX
+tags — resolve every conceptual name to its exact tag + prop schema with the
+\`get-plan-blocks\` tool (see "Block reference" below) before authoring.
 
 - **Schema / migration change** → \`data-model\` for the resulting entities,
   fields, and relations. Flag what moved per field/entity with
@@ -1675,35 +1969,33 @@ the actual diff:
   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 a recap because before/after legibility is the whole point. 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.
+  default for recap code review because before/after legibility is the point;
+  use \`mode: "unified"\` only for a genuinely narrow standalone hunk where
+  side-by-side would hide the code. Give every \`diff\` a one-line \`summary\`
+  saying what the hunk changes and why; it renders as a description above the
+  code so the reviewer reads intent first. Never leave a diff unlabeled.
   For the KEY changed files, attach \`annotations\` to the \`diff\` so the recap
   calls out what each important hunk does — this is the headline affordance for
-  annotating the key files updated. Each annotation is
-  \`{ side?: "before" | "after"; lines: "13" | "13-15"; label?: string; note }\`
-  and anchors to the AFTER-side line numbers by default (set \`side: "before"\` to
-  point at removed lines). Keep it to a few high-signal notes per file, not one
-  per line.
+  annotating the key files updated. Each annotation anchors to the AFTER-side
+  line numbers by default (set \`side: "before"\` to point at removed lines). Keep
+  it to a few high-signal notes per file, not one per line.
   When several key files each need a substantial diff, introduce the group with a
   \`rich-text\` heading block whose markdown is \`## Key changes\`, then place the
-  \`diff\` blocks under it in a reusable \`tabs\` block with
-  \`orientation: "vertical"\` so file labels form a left rail and the selected
-  file's split diff renders on the right. Let that heading label the section — do
-  NOT also set a \`title\` on the \`tabs\` block. Keep each tab label to the file
-  path or a short basename plus directory hint.
+  \`diff\` blocks under it in a reusable \`tabs\` block with horizontal orientation
+  (the default — omit \`orientation\`) so the selected file's split diff gets the
+  full document width. Let that heading label the section — do NOT also set a
+  \`title\` on the \`tabs\` block. Keep each tab label to the file path or a short
+  basename plus directory hint.
   If the recap ends with more than one supporting diff, that trailing diff
-  appendix should be one vertical \`tabs\` block under its own \`## Key changes\`
+  appendix should be one horizontal \`tabs\` block under its own \`## Key changes\`
   heading, not a stack of separate \`diff\` blocks.
 - **Brand-new file or a substantial added block with no meaningful "before"** →
   \`annotated-code\` rather than a one-sided split \`diff\`. Carry the real new code
   with its \`filename\` / \`language\` and anchor a few high-signal notes to the lines
-  that matter (\`{ lines: "12" | "12-18"; label?; note }\`) so the reviewer reads
-  what the new code does, not code for code's sake. Keep split \`diff\` for true
-  before/after hunks where the removed lines still carry meaning, and group
-  several annotated walkthroughs in a vertical \`tabs\` block the same way diffs are
-  grouped.
+  that matter so the reviewer reads what the new code does, not code for code's
+  sake. Keep split \`diff\` for true before/after hunks where the removed lines
+  still carry meaning, and group several annotated walkthroughs in a horizontal
+  \`tabs\` block the same way diffs are grouped.
 - **Files added / removed / renamed** → \`file-tree\` with each entry's \`change\`
   flag (\`added\`, \`removed\`, \`modified\`, \`renamed\`) and a short \`note\`; attach a
   \`snippet\` only when one tells the reviewer something the path does not.
@@ -1713,14 +2005,13 @@ the actual diff:
   or a short state/flow sequence. Use realistic UI surfaces: for a popover
   change, show a popover with its title row, top-right actions, options/fields,
   and any opened prompt/menu anchored to the correct trigger. Keep the body lean:
-  the wireframe carries the UI story, while the file tree and split \`diff\`
+  the wireframe carries the UI story, while the file tree and \`diff\`
   blocks carry implementation evidence.
 - **Architecture or data-flow shift** → \`diagram\` with \`data.html\` / \`data.css\`
   as a two-panel before/after, layered, or swimlane layout, or \`mermaid\` for a
-  quick graph. Use the two-dimensional layouts the Document Quality core
-  prescribes; do not reduce a structural change to a left-to-right chain.
-  Do not use \`diagram\` as a stand-in for rendered UI controls; UI changes need
-  \`wireframe\` blocks.
+  quick graph. Use two-dimensional layouts; do not reduce a structural change to
+  a left-to-right chain. Do not use \`diagram\` as a stand-in for rendered UI
+  controls; UI changes need \`wireframe\` blocks.
   Diagram HTML/CSS should use renderer-owned primitives such as
   \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
   \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; these map to the plan's
@@ -1733,6 +2024,56 @@ the actual diff:
   the objective the diff served, the key decisions visible in it, and the risks a
   reviewer should weigh. This is the only place the model writes freely.
 
+## Block reference — call \`get-plan-blocks\`, do not memorize tags
+
+The conceptual block names above (\`api-endpoint\`, \`data-model\`, \`json-explorer\`,
+\`tabs\`, …) are NOT the JSX tags you author with, and the exact tags, required
+fields, and prop shapes change as the block library evolves. Do not author from
+memorized tags — they drift and silently produce a wrong tag (\`ApiEndpoint\`
+instead of \`Endpoint\`, \`JsonExplorer\` instead of \`Json\`, \`Tabs\` instead of
+\`TabsBlock\`) that errors on import.
+
+**Before writing any structured plan content, call \`get-plan-blocks\` on the
+\`plan\` MCP server.** It returns the authoritative, always-current block
+vocabulary generated live from the app's own block registry — the same config
+the renderer and MDX round-trip use — so it can never be stale even if this
+SKILL.md is an old installed copy:
+
+- \`get-plan-blocks\` (default \`format: "reference"\`) → a compact table of every
+  block's runtime \`type\`, exact MDX \`<Tag>\`, placement, and key data fields.
+  This is your map from each conceptual name above to its real tag and props.
+- \`get-plan-blocks\` with \`format: "schema"\` → the full per-block JSON Schema
+  plus a worked example for each block, when you need exact field types,
+  enums, or nesting (e.g. \`Diff.annotations\`, \`Endpoint.params[].in\`,
+  \`DataModel.entities[].fields[]\`).
+
+Author the recap source against the tags and schemas that call returns. The
+complete set of valid block-level tags is whatever \`get-plan-blocks\` lists;
+any other capitalized tag at the block level is rejected on import with an
+"Unknown plan block" / "did you mean" error. Lowercase HTML tags inside
+\`rich-text\`/markdown prose (\`<div>\`, \`<span>\`, \`<code>\`, \`<br>\`, …) are always
+fine — only capitalized component-style block tags are validated.
+
+A few recap-specific authoring rules the registry table cannot encode:
+
+- Every block takes a REQUIRED \`id\` (unique across the whole plan) plus the
+  shared optional \`summary\` / \`editable\` envelope; give a block a heading by
+  placing a \`rich-text\` block with a Markdown \`###\` heading directly above it
+  (blocks no longer take a \`title\`).
+- \`Endpoint\`: prose \`description\` is the MDX **children** (body between the
+  tags), not an attribute; for a WebSocket upgrade use \`method="GET"\`. Each
+  request/response \`example\` is a JSON **string** (the renderer parses it into
+  the JSON explorer), so keep it a single parseable JSON value.
+- \`TabsBlock\`: the whole \`tabs\` array (including nested child blocks) is ONE
+  JSON \`tabs={[…]}\` prop — there is NO nested \`<Tab>\` element.
+- \`WireframeBlock\`: its body is a single \`<Screen surface ... html=… />\` subtree
+  (nested MDX, not a flat prop); \`html\` must be a single-quoted string or static
+  template literal, never a dynamic \`html={someVar}\` expression. See the
+  Wireframe Quality core above for the HTML rules.
+- \`Diagram\`: the whole payload is one \`data={{ html?, css?, nodes?, edges?, … }}\`
+  attribute and requires either \`html\` or at least one node; \`Mermaid\` is its
+  own separate block (\`source\` text), not a \`Diagram\` prop.
+
 ## Before / After Is The Headline
 
 The recap's center of gravity is the before/after comparison. For document-body
@@ -1744,8 +2085,11 @@ comparisons there are two primitives, and they cover the whole need together:
   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\` with \`mode: "split"\`** — for **code**. The split renders the literal
-  removed and added lines side by side. Use it for the actual hunks.
+- **\`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
@@ -1755,8 +2099,8 @@ explanation. The Wireframe Quality core owns the before/after layout choice —
 the \`columns\` renderer keeps narrow surfaces side by side and auto-stacks wide
 \`desktop\`/\`browser\` frames vertically; never hand-build a side-by-side
 wireframe layout in \`custom-html\`. For document-body
-comparisons, there is no other multi-column primitive — \`columns\` plus split
-\`diff\` are the whole comparison vocabulary. Do not hand-build side-by-side
+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.
 
@@ -2032,6 +2376,10 @@ export const BUILT_IN_APP_SKILLS = {
         skillName: "visual-plan",
         extraSkills: {
             "visual-recap": VISUAL_RECAP_SKILL_MD,
+            "visual-questions": VISUAL_QUESTIONS_SKILL_MD,
+            "ui-plan": UI_PLAN_SKILL_MD,
+            "prototype-plan": PROTOTYPE_PLAN_SKILL_MD,
+            "plan-design": PLAN_DESIGN_SKILL_MD,
         },
         manifest: normalizeAppSkillManifest({
             schemaVersion: 1,
@@ -2045,7 +2393,7 @@ export const BUILT_IN_APP_SKILLS = {
             mcp: { serverName: "agent-native-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add the /visual-plan and /visual-recap skills plus the Plan MCP connector. Authenticate only for hosted/account-backed sharing.",
+                setup: "Install with the Agent-Native CLI to add the /visual-plan, /visual-recap, /ui-plan, /prototype-plan, /plan-design, and /visual-questions skills plus the Plan MCP connector. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
@@ -2060,6 +2408,30 @@ export const BUILT_IN_APP_SKILLS = {
                     path: "/plans",
                     description: "Create a visual recap plan from a PR, commit, branch, or git diff for high-altitude review.",
                 },
+                {
+                    id: "ui-plan",
+                    action: "create-ui-plan",
+                    path: "/plans",
+                    description: "Create a UI-first Agent-Native plan with an optional top pan/zoom wireframe canvas and a refined rich document below.",
+                },
+                {
+                    id: "prototype-plan",
+                    action: "create-prototype-plan",
+                    path: "/plans",
+                    description: "Create a prototype-first Agent-Native plan with a functional live prototype above the document.",
+                },
+                {
+                    id: "plan-design",
+                    action: "create-plan-design",
+                    path: "/plans",
+                    description: "Create a full-fidelity Agent-Native design plan with a Design canvas tab and optional matching Prototype tab.",
+                },
+                {
+                    id: "visual-questions",
+                    action: "create-visual-questions",
+                    path: "/plans",
+                    description: "Create a rich visual intake questionnaire for explicit /visual-questions workflows.",
+                },
             ],
             skills: [
                 {
@@ -2072,6 +2444,26 @@ export const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "visual-recap",
                 },
+                {
+                    path: "skills/visual-questions",
+                    visibility: "exported",
+                    exportAs: "visual-questions",
+                },
+                {
+                    path: "skills/ui-plan",
+                    visibility: "exported",
+                    exportAs: "ui-plan",
+                },
+                {
+                    path: "skills/prototype-plan",
+                    visibility: "exported",
+                    exportAs: "prototype-plan",
+                },
+                {
+                    path: "skills/plan-design",
+                    visibility: "exported",
+                    exportAs: "plan-design",
+                },
             ],
             hostAdapters: [
                 "codex-plugin",
@@ -2139,6 +2531,13 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "visual-recaps": "visual-plans",
     "code-review-recap": "visual-plans",
     "code-review-recaps": "visual-plans",
+    "ui-plan": "visual-plans",
+    "prototype-plan": "visual-plans",
+    "plan-design": "visual-plans",
+    "plan-designs": "visual-plans",
+    "design-plan": "visual-plans",
+    "design-plans": "visual-plans",
+    "visual-questions": "visual-plans",
     "html-plan": "visual-plans",
     "plan-mode": "visual-plans",
     plannotate: "visual-plans",
@@ -2162,6 +2561,10 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
         "visual-plan",
         "visual-recap",
         "code-review-recap",
+        "ui-plan",
+        "prototype-plan",
+        "plan-design",
+        "visual-questions",
         "html-plan",
         "plannotate",
     ],