@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/visual-plan/references/canvas.md

@@ -0,0 +1,121 @@
+# Canvas & artboard placement — single source of truth
+
+This file is the canonical guide for how the visual-plan canvas works: artboard
+placement, lane layout, annotations, patching, and the legacy kit tree. Read it
+in full before authoring or editing any canvas/artboard content; do not author
+canvas layouts from memory or paraphrase these rules per mode.
+
+<!-- SHARED-CORE:canvas-surface START -->
+
+**The coordinate rule.** The `surface` locks each artboard's footprint and
+aspect — never set artboard width/height and never use coordinates inside the
+wireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear
+lanes. Let canvas auto-placement handle simple one-row boards.
+
+**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
+desktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put
+everything in one horizontal strip. Use board-level artboard `x`/`y` to reserve
+lanes with generous empty space: main flow on one row, compact surfaces in their
+own column or row, and loading/error states in a lower row. Keep at least 96px
+between rendered artboard rectangles plus room for annotation gutters; when a
+broad browser/desktop frame sits beside a compact panel/popover, leave at least
+160px so frame borders, labels, and hover controls never touch. Connect only
+neighboring steps; never draw a long connector that skips across unrelated
+frames. Connector labels must sit in open canvas space. If the label would touch
+or cross either artboard, remove the label and explain the transition with a
+nearby annotation instead. Before handoff, inspect the top canvas at default zoom
+and move any frame whose label, connector, or annotation crosses another frame.
+
+**Canvas annotations are designer notes on the artboard.** When a top canvas is
+present, sprinkle Figma-style notes near the frames they explain: a short
+heading, supporting text, and bullets — plain text layers, never bordered or
+shadowed cards, and never a box around a frame. The renderer spaces notes away
+from frames, so place each note by the frame it describes. Use an arrow only to
+point at one specific control or transition; for a broad frame-level note, write
+text beside the frame with no connector. Connectors are for real sequences only —
+never fake "Step 1 → Step 2" lines between independent states.
+
+**Do not create overlapping annotations.** Anchor each ordinary note to the
+frame it explains with `targetId` + `placement` (top/right/bottom/left), and
+omit `type` or use `type: "note"`. The renderer parks notes in a gutter beside
+the frame and lays them out automatically. Do not use `type: "callout"`,
+`type: "text"`, `type: "arrow"`, x/y, or points for ordinary notes; those are
+freeform review-markup layers and must be reserved for intentional markup in
+open canvas space. Reserve arrows for a note that must point at one specific
+control inside a frame; a note that simply sits beside its frame needs no arrow.
+
+**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`
+(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,
+`replace-blocks`, `update-canvas-annotation`) rather
+than regenerating the whole plan. `contentPatches` are part of the public MCP
+action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
+edits. If an agent is working from exported source files, use
+`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds
+frontmatter plus markdown/document blocks, `canvas.mdx` holds
+`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the
+patch action normalizes the MDX back into the same JSON runtime model. JSON is
+the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit `rich-text` prose inline; agents should still use
+`update-rich-text` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+Never send a partial top-level `content` object as a shortcut to add a canvas,
+frame, or block: `content` is a full structured replacement, so omitted blocks
+or surfaces can disappear. If a full replacement is truly unavoidable, read the
+complete source/JSON first, include every existing block and surface in the new
+payload, and verify the source/export immediately after the update.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard
+you place on the canvas must carry an `html` wireframe or reference a wireframe
+block via `blockId`; when using `blockId`, the referenced `wireframe` /
+`legacy-wireframe` block must remain in the plan. If you remove a duplicate
+wireframe from the document body, first move its `data` inline onto the
+corresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A
+label-only frame or a frame pointing at a deleted block renders empty and is
+rejected at parse time. If you only have a title, write it as a section header or
+annotation, not an empty artboard.
+
+**UI mockups belong in the top visual review area.** Static UI/product visuals
+live on the canvas; multi-step UI flows get both canvas wireframes and a
+prototype. When the user asks for a mockup, UI state, loading state, layout,
+screen, or visual comparison, make the canvas the primary home for that static
+visual. When the user asks for a prototype or the plan contains a sequence the
+reviewer must feel, keep the canvas artboards and add `content.prototype` so the
+top surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay
+inline in the document (the SKILL.md Visual Surface Choice section owns that
+rule) unless the user explicitly asks for a spatial board. Document blocks
+can explain, compare, or map implementation, but they should not host the
+primary UI mockup or prototype just because `custom-html`, screenshots, or prose
+are easier to produce. If the canvas/prototype surface cannot represent the
+requested UI fidelity, still keep the closest top-surface representation and
+call out or extend the needed renderer capability. A skeleton/loading mockup
+also lives in a canvas artboard — never move a mockup out of the canvas.
+
+**Storyboards are canvas artifacts, not document diagrams.** When the requested
+output is a product flow, onboarding journey, "light storyboard", or canvas
+wireframe, author the flow as multiple top-canvas artboards with real screen
+content and neighboring connectors. Keep document-body `diagram` blocks for
+architecture and mechanics that are not themselves user-visible screens. A
+storyboard made from a single inline HTML diagram is the wrong surface.
+
+For abstract product concepts, use the canvas to create the first "I get it"
+moment: one real app state near the top showing how the concept appears to a
+user, followed by separate annotations or diagrams for mechanics. Do not make
+the first artboard a hybrid of app UI and architecture notes; the app screen
+should be inspectable as product UI on its own.
+
+**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit
+nodes instead of `html`; the renderer still accepts and displays it so saved
+plans round-trip, but new plans emit `html`. Do not author fresh kit-tree
+screens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,
+`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard
+with kit-tree children is a defect: replace it with
+`<Screen surface="..." html={...} />` using the HTML wireframe rules. The HTML
+path is the one that gets the renderer-owned surface sizing, theme tokens,
+sketch/clean toggle, and safe text layout used by good document-body
+wireframes. Likewise, old or imported plans may carry coordinate-based regions
+or free-float x/y on notes; those are legacy escape hatches the renderer still
+shows but you must never produce. The gutter parks notes by `targetId` +
+`placement`, and the coordinate rule at the top of this file governs all
+new-plan placement.
+
+<!-- SHARED-CORE:canvas-surface END -->

package/corpus/templates/tasks/.agents/skills/visual-plan/references/document-quality.md

@@ -0,0 +1,178 @@
+# Plan document quality — single source of truth
+
+This file is the canonical quality bar for the plan document below the canvas:
+how it reads, which blocks to use, how open questions are surfaced, and the
+pre-handoff check. Read it in full before authoring the plan document; it is the
+quality bar. Do not write the document from memory or paraphrase these rules per
+mode.
+
+<!-- SHARED-CORE:document-quality START -->
+
+**The document is a serious technical plan, not marketing.** Write it the way a
+strong Claude or Codex implementation plan reads: outcome-first, prose-first,
+self-contained, and specific. State the objective and what "done" means, the
+scope and non-goals, the proposed approach with the key decisions and their
+rationale, ordered steps that name real files, symbols, actions, and data
+shapes, the risks, and a closing verification step (tests, build, or a checkable
+behavior). Replace vague prose with specifics; never ship a step like "make it
+work." No hero art, gradients, logos, nav bars, slogans, value props, giant
+landing-page headings, or marketing cards unless the user explicitly asks.
+
+**Every published plan must stand alone.** Even when the agent is revising an
+existing plan, the output is a plan to do the work, not a changelog of the
+conversation. Do not write phrases like "preserve the previous plan", "do not
+drop the old idea", "as discussed above", "this revision", "unlike the prior
+version", or "correction from the earlier plan". Fold the right decisions into
+the plan as normal objective, architecture, scope, and roadmap prose. A reviewer
+who opens the plan from a link with no chat history should understand it. Avoid
+negative framing that only makes sense against absent context ("not the old
+mode", "not just X") unless the contrast is defined in the plan and genuinely
+helps; state the positive model directly.
+
+**Make abstract plans instantly legible.** If the idea is broad, strategic, or
+intended for a third-party reviewer, put one concrete product snapshot near the
+top before dense architecture, mode tables, manifests, or roadmaps. For
+UI-capable concepts, that snapshot is usually a top-canvas app state plus a
+short paragraph that says what the user sees and what changes under the hood.
+Then put mechanics, data flow, sync boundaries, and implementation detail in
+separate diagrams or document sections.
+
+**Preserve the user's level of abstraction.** A motivating use case is not
+automatically the architecture. When the prompt describes a broader framework,
+product mode, or reusable primitive, separate the reusable core from specific
+apps, providers, customers, scripts, or launch examples. Use the concrete
+example to make the plan understandable, then make clear which parts are core,
+which are app-specific adapters, and which are future examples.
+
+**When top visuals exist, they and the document never duplicate each other.**
+For UI work, the UI story lives in the top visual surface: canvas artboards for
+static inspection, plus prototype tabs when the flow should be functional. The
+document carries the technical depth the visuals cannot show — concrete
+file/symbol maps, API and data contracts, code snippets, migration or
+implementation phases, risks, and validation. For architecture/code reviews,
+invert that: the document is the visual surface, and each recommendation
+carries its own nearby inline `diagram` / `data-model` block plus file
+evidence (the `diagram` bullet below owns how to author those diagrams).
+Repeat a wireframe in the document only for a genuinely new detail view or
+comparison. Skip the visual surface entirely for non-visual work and write a
+clean rich document. For a simple binary UI visual choice, show the two
+directions in the canvas only; do not repeat the same options as body
+wireframes or prose. Put the actual choice in the bottom "Open Questions" form.
+
+**Use the right block, and make it carry substance.** For the authoritative,
+machine-checked list of block types and their data schemas, call `get-plan-blocks`
+— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
+so you never emit a block the editor cannot render or round-trip:
+
+- `rich-text` for plan prose with real bold/italic/code/links and nested lists.
+- `annotated-code` for the file map: when a load-bearing file is worth
+  highlighting, prefer the annotated walkthrough over a bare `code` block — carry
+  the real, syntax-highlighted code AND anchor short margin notes to the lines
+  that actually change (the new action, the changed schema, the wiring point), so
+  the reader sees what matters and why instead of code for code's sake. Each
+  annotation is `{ lines: "12" | "12-18"; label?; note }`; keep a few high-signal
+  notes per file, not one per line. Highlight only the files worth reading; never
+  an exhaustive list of every touched file, and never a prose-only description of
+  a file. Drop to a plain `code` block only for a throwaway snippet with nothing
+  to call out. When more than one file matters, group the blocks in a vertical
+  `tabs` block (the standard tab primitive) rather than a bespoke container. If
+  the exact code is unknown, show the smallest plausible planned shape or a
+  commented stub naming what to fill in. (`code-tabs` and `implementation-map`
+  are legacy: their renderers stay for old plans, but do not author new ones.)
+- For a decision: if the reviewer must still pick between a genuinely-open
+  either/or, put it in the bottom Open Questions `question-form` as a `single`
+  question — one option per real alternative, each with a short detail and
+  `recommended: true` on the one you would choose; do not also restate the same
+  choice elsewhere. If you have already committed to an approach, state it as
+  settled prose or a `callout` with `tone="decision"`, optionally with a
+  `columns` block for a side-by-side comparison of the options you weighed — not
+  as a confusing mid-document form for a question you have already answered.
+- `columns` for side-by-side before/after or current/target comparisons where
+  each side needs real nested blocks; label the columns clearly and avoid
+  stacking comparison blocks vertically when parallel reading is the point.
+- `diagram` for two-dimensional architecture, dependency, data-flow, or state
+  relationships, only when it clarifies something real. Prefer standard
+  two-dimensional layouts — paired before/after panels, layered diagrams,
+  swimlanes, dependency maps, matrices, or grouped regions; do not default to
+  left-to-right chains, and use a line only when the relationship is truly a
+  sequence. Do not use a body `diagram` as the primary artifact for a requested
+  product canvas, light storyboard, UI flow, screen flow, or wireframe; those
+  belong in the top canvas as artboards with `Screen` wireframes first. Use
+  diagrams below that canvas only for architecture, data flow, or implementation
+  mechanics. For architecture/code
+  diagrams, prefer `data.html` / `data.css` with semantic HTML and inline SVG so
+  the diagram can use panels, layers, matrices, arrows, annotations, and
+  responsive layout directly. Author diagram HTML with renderer-owned primitives
+  like `.diagram-panel`, `.diagram-card`, `.diagram-node`, `.diagram-box`,
+  `.diagram-pill`, `.diagram-muted`, and `[data-rough]`; they map to the plan's
+  Tailwind theme variables through `--wf-ink`, `--wf-muted`, `--wf-line`,
+  `--wf-paper`, `--wf-card`, `--wf-accent`, `--wf-accent-soft`, `--wf-warn`, and
+  `--wf-ok`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
+  set `font-family` and do not hard-code hex, rgb, or hsl colors in diagram HTML
+  or CSS. Leave room for the sketch font: keep labels short, give nodes generous
+  width, and place boundary/annotation labels in unused space instead of over
+  nodes; labels must not overlap nodes, connectors, or each other. For small
+  text/SVG changes to an existing HTML diagram, use `patch-diagram-html` with a
+  unique `find`/`replace` snippet instead of resending the whole `data.html`
+  string. Use legacy `nodes` / `edges` only for small previews or truly
+  sequential flows. In architecture/code plans, prefer a repeated section rhythm:
+  recommendation title, confidence and category badges, code-path evidence, a
+  local before/after or current/target spatial diagram, then concise
+  Problem/Solution/Why text.
+- `tabs` for multiple states, directions, or comparisons. A tab that reveals
+  only prose usually means the plan is under-specified — include a relevant
+  visual unless the tab is intentionally document-only.
+- `table`, `checklist`, `callout` for scannable structure.
+
+**Open questions live at the bottom as a form when answers would change the
+plan.** Surface answerable unresolved decisions in a final `question-form`
+block titled "Open Questions" so the renderer presents it as a distinct section.
+That bottom form is the ONLY place that enumerates the open questions: never add
+a second "Open Questions" heading, list, or recap of the same questions earlier
+in the document. A one-line pointer in the overview prose ("a few decisions are
+still open — see Open Questions below") is fine, but do not reproduce the
+question list or a parallel questions/decisions section above it.
+Use `single` or `multi` for clear choices, `freeform` for constraints,
+`recommended: true` for the default you would pick, and option `wireframe` /
+`diagram` previews only when the options are not already visible in the top
+canvas. `single` and `multi` questions always render a write-in field so a
+reviewer can answer with a custom option — never add an explicit "Other" option
+yourself; set `allowOther: false` only when a free-text answer makes no sense.
+Keep non-answerable assumptions or risks as concise `callout` blocks in
+the relevant section. Never bury a questions/decisions wall inside the plan
+narrative, and never ask the same question twice.
+
+For complex plans, do not end without an open-question audit. If architecture,
+scope, UX, data shape, rollout, provider mapping, or ownership still depends on
+a choice, either commit to a recommendation with rationale or add it to the
+bottom form with a recommended default. A complex plan with no open questions is
+fine only when every meaningful decision has been explicitly made.
+
+**Verification must exercise the real workflow.** The final verification section
+should go beyond typecheck/unit tests when the plan changes UI, local files,
+sync, providers, browser behavior, or multi-app flows. Include at least one
+end-to-end smoke that matches the user journey, such as a fresh repo/folder,
+real manifest or data fixture, browser interaction, save/sync action, and an
+on-disk or database assertion. Name the command or manual browser path when it
+is known.
+
+**`custom-html` is a bounded escape hatch only** — a single complete fragment
+inside a block, never `html`/`head`/`body`/`script` tags, never a generic
+placeholder, density demo, or proof that custom HTML works. Prefer the native
+blocks for normal plans. For architecture/code reviews, use `diagram`
+`data.html` / `data.css` for rich local HTML/SVG diagrams instead of
+`custom-html`. For UI/product work, `custom-html` is never the primary home for a
+requested mockup, UI state, or visual comparison. If UI fidelity requires
+HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
+for that artifact type, not moving the mockup into the document.
+When `custom-html` is genuinely needed, author it against the sandbox-provided
+theme tokens (`--wf-paper`, `--wf-card`, `--wf-ink`, `--wf-muted`,
+`--wf-line`, `--wf-radius`, and the matching `--plan-*` aliases). Do not hardcode
+hex/rgb/hsl light palettes such as white cards with dark ink; the same fragment
+must read in dark mode without a plan-specific patch.
+
+**Before handoff, open the plan and check it.** Fix overlap, excessive
+whitespace, clipped fragments, misleading inactive controls, poor contrast, and
+unreadable diagrams before asking for approval.
+
+<!-- SHARED-CORE:document-quality END -->

package/corpus/templates/tasks/.agents/skills/visual-plan/references/exemplar.md

@@ -0,0 +1,62 @@
+# Good vs. bad exemplar — single source of truth
+
+This file is the canonical worked example of a great plan (and the anti-patterns
+to avoid). Read it alongside the document-quality and canvas references before
+authoring a plan; it is the bar these plans must clear.
+
+<!-- SHARED-CORE:exemplar START -->
+
+**GOOD.** A UI-first plan for a todo app: a canvas with a `desktop` artboard whose
+`data.html` is a real flex layout — a sidebar of links (`Inbox 12`, `Today 4`,
+`Done`), a main column with an `<h1>Today</h1>`, accent `.wf-pill`s for the
+filters, a muted section label `OVERDUE`, and `.wf-card` task rows carrying real
+titles, due dates, and a primary `button.primary` — styled only through bare
+elements, helper classes, and `--wf-*` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, a few `code` blocks (grouped in a vertical `tabs` block when
+more than one) showing the real shape of the load-bearing files, a `callout`
+with `tone="decision"` stating the chosen approach with a `columns` block
+weighing the two real options behind it,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+`data-goto` controls for the sequence. This is the bar.
+
+**GOOD.** A broad product-architecture plan opens with a plain recommendation
+and one concrete app state before the abstraction. The first canvas artboard is
+pure product UI that matches the current app shell; nearby notes explain the
+user-visible delta. A separate diagram below shows the mechanics, such as file
+or data flow. The document then separates the reusable core from app/provider
+adapters and examples, covers contracts, folder or schema shape, sync
+boundaries, roadmap, non-goals, a bottom Open Questions form for unresolved
+decisions, and a verification section with at least one realistic end-to-end
+smoke. A reviewer who was not in the chat gets the idea from the top snapshot
+before reading the technical plan.
+
+**GOOD.** A `/visual-plan` for a backend architecture review: no top canvas.
+The document opens with context and a legend, then repeats recommendation cards:
+title, confidence/category badges, a monospace grid of real file paths, one
+inline two-dimensional before/after or layered architecture diagram, and terse
+Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
+space to show boundaries, layers, and ownership; it is not a default
+left-to-right chain. The plan ends with a top recommendation and a bottom
+question-form only if the next architecture direction is genuinely open. This is
+better than a top canvas because each diagram is local to the claim it supports.
+
+**BAD.** A `data.html` with hard-coded hex colors, a `font-family`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree `screen`
+instead of `html`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document `custom-html` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Also bad: an architecture-only plan forced into a top canvas of
+labeled boxes with overlapping text, where the actual code evidence and
+recommendations live elsewhere; a product wireframe that mixes a real screen
+with repo names, file-contract arrows, architecture explanations, or a made-up
+permanent inspector; and a plan that describes itself as a revision of a prior
+conversation instead of a standalone proposal. Never produce this.
+
+<!-- SHARED-CORE:exemplar END -->

package/corpus/templates/tasks/.agents/skills/visual-plan/references/wireframe.md

@@ -0,0 +1,264 @@
+# 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.
+
+**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>`.
+
+**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.** 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 -->