@agent-native/core 0.66.1 → 0.66.3

package/dist/cli/skills.js

@@ -616,10 +616,14 @@ desktop frames plus compact \`mobile\`, \`popover\`, or \`panel\` surfaces, do n
 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. Connect
-only neighboring steps; never draw a long connector that skips across unrelated
-frames. Before handoff, inspect the top canvas at default zoom and move any
-frame whose label, connector, or annotation crosses another frame.
+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
@@ -685,6 +689,13 @@ 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
@@ -692,10 +703,16 @@ 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, but new
-plans emit \`html\`. Do not author fresh kit-tree screens - write the HTML mockup
-instead. 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
+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.
@@ -790,7 +807,11 @@ so you never emit a block the editor cannot render or round-trip:
   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. For architecture/code
+  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
@@ -1094,10 +1115,15 @@ ownership, privacy, sharing, and branding needs.
 
 By default, create the plan via the Plan MCP connector. NEVER hand the plan over
 as inline chat content — no Markdown prose, ASCII sketch, table, or fenced
-wireframe. If the connector's tools are missing, do NOT fall back to inline
-output: the usual cause is a connector that did not finish connecting this
-session (it registers zero tools), not auth. Stop and give the user the exact
-restore step for their current client: in Codex/Codex Desktop run
+wireframe. Some clients lazy-load connector tools through a deferred tool
+registry instead of showing the \`plan\` namespace upfront; before declaring the
+connector missing, search/load tools with the host's discovery surface
+(\`tool_search\` when available) for \`create_visual_plan\`, \`create_ui_plan\`, or
+\`get_plan_blocks\`, then use the Plan MCP tools it exposes. If the connector's
+tools are still missing after discovery, do NOT fall back to inline output: the
+usual cause is a connector that did not finish connecting this session (it
+registers zero tools), not auth. Stop and give the user the exact restore step
+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 same reconnect command with
@@ -1204,6 +1230,14 @@ beside frames with \`targetId\` plus \`placement\`; keep implementation details,
 tradeoffs, file maps, data contracts, risks, and verification in the document
 body below the canvas.
 
+When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what
+this looks like", treat that as a canvas-first request. Make one artboard per
+user-visible state, connect only adjacent transitions, and use short canvas
+annotations for the product notes. Do not substitute a document-body \`diagram\`
+block for the requested storyboard just because HTML diagrams are faster to
+write; diagrams belong below the canvas for backend mechanics, architecture, or
+data-flow explanation.
+
 Keep product wireframes and explanatory/meta diagrams separate. Start with pure
 screens that look like the app state under discussion, without callout prose or
 architecture notes embedded inside the UI. Put arrows, labels, contracts, data
@@ -1262,6 +1296,12 @@ in lanes, annotations are plain-text designer notes anchored by
 authoring or editing ANY canvas, artboard, or annotation, READ
 \`references/canvas.md\` in this skill directory — it is the single source of truth
 for canvas/artboard mechanics. Do not author canvas layouts from memory.
+Canvas artboards use the same HTML wireframe path as document-body
+\`WireframeBlock\` screens: author \`<Screen surface="..." html={...} />\` with a
+semantic HTML fragment. Do not author fresh kit-tree children such as
+\`<FrameScreen>\`, \`<Card>\`, \`<Row>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags;
+those are legacy compatibility markup for old plans and produce brittle canvas
+layouts.
 
 ## Document quality — read \`references/document-quality.md\`
 
@@ -1557,13 +1597,20 @@ 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, do NOT improvise an
-inline recap as a fallback. Do not report the connector as disconnected just
-because it is named \`agent-native-plans\` instead of \`plan\`. The usual cause is a
-connector that did not finish connecting this session (it registers zero tools),
-NOT necessarily an auth problem — so do not assume the user must authenticate.
-Stop and tell the user how to restore it for their current client: in
+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
@@ -1745,6 +1792,19 @@ 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-plans/references/canvas.md\`
+
+When a recap includes a top canvas, storyboard, or flow view, READ
+\`../visual-plans/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
@@ -1903,8 +1963,10 @@ instead of \`Endpoint\`, \`JsonExplorer\` instead of \`Json\`, \`Tabs\` instead
 
 **Before writing any structured plan content, fetch/read the block catalog.** In
 hosted or self-hosted mode, call \`get-plan-blocks\` on the Plan MCP connector
-(\`plan\` or legacy \`agent-native-plans\`). In local-files mode, or when the skill
-was installed as plain text and no MCP tools are registered, run
+(\`plan\` or legacy \`agent-native-plans\`). If no Plan tools are visible yet in a
+lazy-loading client, search/load them through the host's tool discovery surface
+first (\`tool_search\` when available). In local-files mode, or when the skill was
+installed as plain text and no MCP tools are registered after discovery, run
 \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read that
 file first. The CLI command calls the public no-auth \`get-plan-blocks\` route and
 sends no plan/recap content. If network access is unavailable, use the bundled