@agent-native/core 0.96.0 → 0.98.0

package/dist/cli/skills-content/assets-skill.d.ts

@@ -0,0 +1,2 @@
+export declare const ASSETS_SKILL_MD = "---\nname: assets\ndescription: >-\n  Use Assets for image or video generation requests, brand-safe media,\n  human picker UI, search/list/export actions, and cross-app asset selection.\n  Prefer this over generic image tools when installed.\nmetadata:\n  visibility: exported\n---\n\n# Assets\n\nUse the Assets app when a workflow needs reusable brand media, a human picker,\nor generated image/video assets that another app can reference by ID and URL.\nWhen this skill is available, route plain image-generation requests here instead\nof using a generic image generator.\n\n## Choose The Path\n\n- Use `open-asset-picker` when a person should browse, search, generate, and\n  select an asset in UI. Pass `mediaType: \"image\"` by default, or\n  `mediaType: \"video\"` for video libraries. When the user asks to create a\n  specific image and choose the best option, pass `prompt`,\n  `autoGenerate: true`, and `count: 3` so the picker opens with candidates\n  to preview and select.\n- Use unattended actions when the agent already knows what to do:\n  `search-assets`, `list-assets`, `generate-image`,\n  `generate-image-batch`, `generate-video`,\n  `refresh-generation-run`, and `export-asset`.\n- Use browser/deep-link fallback when the host cannot render MCP Apps inline.\n  Surface the returned picker link. If it opens in a normal browser tab, have\n  the user select an asset there and paste back the copied handoff summary.\n  Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts; do not\n  promise inline MCP App rendering there.\n  If the skill instructions are available but the MCP tool namespace has not\n  appeared yet, use the Assets browser fallback URL shape instead of switching\n  to a generic generator:\n  `https://assets.agent-native.com/library?mediaType=image&prompt=...&autoGenerate=1&count=3`.\n  When reporting the final selected image in Codex or Claude Code, include the\n  asset link and, if an inline preview is important, download the selected\n  `previewUrl`/`downloadUrl` to a local temp image and embed that absolute\n  local path. Remote CDN markdown images can fail to render in code-editor chat\n  surfaces.\n\n## Image And Video Workflows\n\n1. Pick or match the library with `list-libraries` or `match-library`.\n2. For images, call `generate-image` or `generate-image-batch`. Image\n   actions are synchronous: one batch call should return the finished image\n   candidates, so do not poll or regenerate unless a returned slot failed.\n3. For videos, call `generate-video` and poll `refresh-generation-run`\n   until the run completes.\n4. Preserve returned `assetId`, `runId`, `previewUrl`, `downloadUrl`,\n   media type, and dimensions so the caller can attach or embed the result.\n\n## Cross-App Use\n\n- Hosted default: connect `https://assets.agent-native.com/_agent-native/mcp`.\n  Do not put shared secrets in skill files.\n- For CLI/code-editor clients, keep any `npx @agent-native/core@latest connect` command\n  running until browser authorization finishes. Stopping it early can leave the\n  browser approved but the local MCP config unwritten. Restart or reload the\n  agent client after installing or connecting if Assets tools do not appear in\n  the live session.\n- Local customization: use `npx @agent-native/core@latest app-skill launch --local` from an\n  Assets app-skill manifest, or pass `--into <path>` for editable source.\n- Do not call image/video providers directly from another app. Assets owns\n  generation, picker UI, search/list/export, and asset context.\n- If an Assets tool call returns `Session terminated`, `needs auth`, or\n  another connector/session error, do not keep retrying the tool. Stop and give\n  the user the reconnect step: in Claude Code run `/mcp` and choose\n  Authenticate/Reconnect for the Assets connector; from any terminal run\n  `npx -y @agent-native/core@latest reconnect https://assets.agent-native.com` \u2014 this\n  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix\n  auth. Continue once the connector is available.\n- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the\n  host-exposed Assets tools after restart/reload, or use the returned\n  browser/deep-link fallback.\n- If a batch image generation request times out in browser fallback, retry with\n  `count: 1` only after telling the user the multi-candidate request timed out.\n- If you inspect local MCP config, redact `Authorization`, `http_headers`,\n  and token values. Never paste bearer tokens into chat or logs.\n";
+//# sourceMappingURL=assets-skill.d.ts.map

package/dist/cli/skills-content/assets-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets-skill.d.ts","sourceRoot":"","sources":["../../../src/cli/skills-content/assets-skill.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,m9IAkF3B,CAAC"}

package/dist/cli/skills-content/assets-skill.js

@@ -0,0 +1,84 @@
+export const ASSETS_SKILL_MD = `---
+name: assets
+description: >-
+  Use Assets for image or video generation requests, brand-safe media,
+  human picker UI, search/list/export actions, and cross-app asset selection.
+  Prefer this over generic image tools when installed.
+metadata:
+  visibility: exported
+---
+
+# Assets
+
+Use the Assets app when a workflow needs reusable brand media, a human picker,
+or generated image/video assets that another app can reference by ID and URL.
+When this skill is available, route plain image-generation requests here instead
+of using a generic image generator.
+
+## Choose The Path
+
+- Use \`open-asset-picker\` when a person should browse, search, generate, and
+  select an asset in UI. Pass \`mediaType: "image"\` by default, or
+  \`mediaType: "video"\` for video libraries. When the user asks to create a
+  specific image and choose the best option, pass \`prompt\`,
+  \`autoGenerate: true\`, and \`count: 3\` so the picker opens with candidates
+  to preview and select.
+- Use unattended actions when the agent already knows what to do:
+  \`search-assets\`, \`list-assets\`, \`generate-image\`,
+  \`generate-image-batch\`, \`generate-video\`,
+  \`refresh-generation-run\`, and \`export-asset\`.
+- Use browser/deep-link fallback when the host cannot render MCP Apps inline.
+  Surface the returned picker link. If it opens in a normal browser tab, have
+  the user select an asset there and paste back the copied handoff summary.
+  Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts; do not
+  promise inline MCP App rendering there.
+  If the skill instructions are available but the MCP tool namespace has not
+  appeared yet, use the Assets browser fallback URL shape instead of switching
+  to a generic generator:
+  \`https://assets.agent-native.com/library?mediaType=image&prompt=...&autoGenerate=1&count=3\`.
+  When reporting the final selected image in Codex or Claude Code, include the
+  asset link and, if an inline preview is important, download the selected
+  \`previewUrl\`/\`downloadUrl\` to a local temp image and embed that absolute
+  local path. Remote CDN markdown images can fail to render in code-editor chat
+  surfaces.
+
+## Image And Video Workflows
+
+1. Pick or match the library with \`list-libraries\` or \`match-library\`.
+2. For images, call \`generate-image\` or \`generate-image-batch\`. Image
+   actions are synchronous: one batch call should return the finished image
+   candidates, so do not poll or regenerate unless a returned slot failed.
+3. For videos, call \`generate-video\` and poll \`refresh-generation-run\`
+   until the run completes.
+4. Preserve returned \`assetId\`, \`runId\`, \`previewUrl\`, \`downloadUrl\`,
+   media type, and dimensions so the caller can attach or embed the result.
+
+## Cross-App Use
+
+- Hosted default: connect \`https://assets.agent-native.com/_agent-native/mcp\`.
+  Do not put shared secrets in skill files.
+- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
+  running until browser authorization finishes. Stopping it early can leave the
+  browser approved but the local MCP config unwritten. Restart or reload the
+  agent client after installing or connecting if Assets tools do not appear in
+  the live session.
+- Local customization: use \`npx @agent-native/core@latest app-skill launch --local\` from an
+  Assets app-skill manifest, or pass \`--into <path>\` for editable source.
+- Do not call image/video providers directly from another app. Assets owns
+  generation, picker UI, search/list/export, and asset context.
+- If an Assets tool call returns \`Session terminated\`, \`needs auth\`, or
+  another connector/session error, do not keep retrying the tool. Stop and give
+  the user the reconnect step: in Claude Code run \`/mcp\` and choose
+  Authenticate/Reconnect for the Assets connector; from any terminal run
+  \`npx -y @agent-native/core@latest reconnect https://assets.agent-native.com\` — this
+  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
+  auth. Continue once the connector is available.
+- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
+  host-exposed Assets tools after restart/reload, or use the returned
+  browser/deep-link fallback.
+- If a batch image generation request times out in browser fallback, retry with
+  \`count: 1\` only after telling the user the multi-candidate request timed out.
+- If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
+  and token values. Never paste bearer tokens into chat or logs.
+`;
+//# sourceMappingURL=assets-skill.js.map

package/dist/cli/skills-content/assets-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets-skill.js","sourceRoot":"","sources":["../../../src/cli/skills-content/assets-skill.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkF9B,CAAC","sourcesContent":["export const ASSETS_SKILL_MD = `---\nname: assets\ndescription: >-\n  Use Assets for image or video generation requests, brand-safe media,\n  human picker UI, search/list/export actions, and cross-app asset selection.\n  Prefer this over generic image tools when installed.\nmetadata:\n  visibility: exported\n---\n\n# Assets\n\nUse the Assets app when a workflow needs reusable brand media, a human picker,\nor generated image/video assets that another app can reference by ID and URL.\nWhen this skill is available, route plain image-generation requests here instead\nof using a generic image generator.\n\n## Choose The Path\n\n- Use \\`open-asset-picker\\` when a person should browse, search, generate, and\n  select an asset in UI. Pass \\`mediaType: \"image\"\\` by default, or\n  \\`mediaType: \"video\"\\` for video libraries. When the user asks to create a\n  specific image and choose the best option, pass \\`prompt\\`,\n  \\`autoGenerate: true\\`, and \\`count: 3\\` so the picker opens with candidates\n  to preview and select.\n- Use unattended actions when the agent already knows what to do:\n  \\`search-assets\\`, \\`list-assets\\`, \\`generate-image\\`,\n  \\`generate-image-batch\\`, \\`generate-video\\`,\n  \\`refresh-generation-run\\`, and \\`export-asset\\`.\n- Use browser/deep-link fallback when the host cannot render MCP Apps inline.\n  Surface the returned picker link. If it opens in a normal browser tab, have\n  the user select an asset there and paste back the copied handoff summary.\n  Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts; do not\n  promise inline MCP App rendering there.\n  If the skill instructions are available but the MCP tool namespace has not\n  appeared yet, use the Assets browser fallback URL shape instead of switching\n  to a generic generator:\n  \\`https://assets.agent-native.com/library?mediaType=image&prompt=...&autoGenerate=1&count=3\\`.\n  When reporting the final selected image in Codex or Claude Code, include the\n  asset link and, if an inline preview is important, download the selected\n  \\`previewUrl\\`/\\`downloadUrl\\` to a local temp image and embed that absolute\n  local path. Remote CDN markdown images can fail to render in code-editor chat\n  surfaces.\n\n## Image And Video Workflows\n\n1. Pick or match the library with \\`list-libraries\\` or \\`match-library\\`.\n2. For images, call \\`generate-image\\` or \\`generate-image-batch\\`. Image\n   actions are synchronous: one batch call should return the finished image\n   candidates, so do not poll or regenerate unless a returned slot failed.\n3. For videos, call \\`generate-video\\` and poll \\`refresh-generation-run\\`\n   until the run completes.\n4. Preserve returned \\`assetId\\`, \\`runId\\`, \\`previewUrl\\`, \\`downloadUrl\\`,\n   media type, and dimensions so the caller can attach or embed the result.\n\n## Cross-App Use\n\n- Hosted default: connect \\`https://assets.agent-native.com/_agent-native/mcp\\`.\n  Do not put shared secrets in skill files.\n- For CLI/code-editor clients, keep any \\`npx @agent-native/core@latest connect\\` command\n  running until browser authorization finishes. Stopping it early can leave the\n  browser approved but the local MCP config unwritten. Restart or reload the\n  agent client after installing or connecting if Assets tools do not appear in\n  the live session.\n- Local customization: use \\`npx @agent-native/core@latest app-skill launch --local\\` from an\n  Assets app-skill manifest, or pass \\`--into <path>\\` for editable source.\n- Do not call image/video providers directly from another app. Assets owns\n  generation, picker UI, search/list/export, and asset context.\n- If an Assets tool call returns \\`Session terminated\\`, \\`needs auth\\`, or\n  another connector/session error, do not keep retrying the tool. Stop and give\n  the user the reconnect step: in Claude Code run \\`/mcp\\` and choose\n  Authenticate/Reconnect for the Assets connector; from any terminal run\n  \\`npx -y @agent-native/core@latest reconnect https://assets.agent-native.com\\` — this\n  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix\n  auth. Continue once the connector is available.\n- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the\n  host-exposed Assets tools after restart/reload, or use the returned\n  browser/deep-link fallback.\n- If a batch image generation request times out in browser fallback, retry with\n  \\`count: 1\\` only after telling the user the multi-candidate request timed out.\n- If you inspect local MCP config, redact \\`Authorization\\`, \\`http_headers\\`,\n  and token values. Never paste bearer tokens into chat or logs.\n`;\n"]}

package/dist/cli/skills-content/canvas.d.ts

@@ -0,0 +1,4 @@
+export declare const CANVAS_SURFACE_CORE = "<!-- SHARED-CORE:canvas-surface START -->\n\n**The coordinate rule.** The `surface` locks each artboard's footprint and\naspect \u2014 never set artboard width/height and never use coordinates inside the\nwireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear\nlanes. Let canvas auto-placement handle simple one-row boards.\n\n**Lay out mixed canvases in lanes.** When a canvas contains broad browser /\ndesktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put\neverything in one horizontal strip. Use board-level artboard `x`/`y` to reserve\nlanes with generous empty space: main flow on one row, compact surfaces in their\nown column or row, and loading/error states in a lower row. Keep at least 96px\nbetween rendered artboard rectangles plus room for annotation gutters; when a\nbroad browser/desktop frame sits beside a compact panel/popover, leave at least\n160px so frame borders, labels, and hover controls never touch. Connect only\nneighboring steps; never draw a long connector that skips across unrelated\nframes. Connector labels must sit in open canvas space. If the label would touch\nor cross either artboard, remove the label and explain the transition with a\nnearby annotation instead. Before handoff, inspect the top canvas at default zoom\nand move any frame whose label, connector, or annotation crosses another frame.\n\n**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. `browser` frames occupy roughly 700 \u00D7 600 board units; `desktop` frames roughly 900 \u00D7 700 board units. Apply these minimum x/y gaps when placing frames explicitly \u2014 any less and frames will touch or overlap:\n\n- x-gap between `browser` frames: **\u2265 1100** (700-unit frame + 400-unit gutter)\n- x-gap between `desktop` frames: **\u2265 1300** (900-unit frame + 400-unit gutter)\n- y-gap between rows of any surface: **\u2265 1400** (includes frame height + section header + buffer)\n\nWhen in doubt, use larger values \u2014 the canvas auto-zooms to fit everything.\n\n**Canvas annotations are designer notes on the artboard.** When a top canvas is\npresent, sprinkle design-review notes near the frames they explain: a short\nheading, supporting text, and bullets \u2014 plain text layers, never bordered or\nshadowed cards, and never a box around a frame. The renderer spaces notes away\nfrom frames, so place each note by the frame it describes. Use an arrow only to\npoint at one specific control or transition; for a broad frame-level note, write\ntext beside the frame with no connector. Connectors are for real sequences only \u2014\nnever fake \"Step 1 \u2192 Step 2\" lines between independent states.\n\n**Do not create overlapping annotations.** Anchor each ordinary note to the\nframe it explains with `targetId` + `placement` (top/right/bottom/left), and\nomit `type` or use `type: \"note\"`. The renderer parks notes in a gutter beside\nthe frame and lays them out automatically. Do not use `type: \"callout\"`,\n`type: \"text\"`, `type: \"arrow\"`, x/y, or points for ordinary notes; those are\nfreeform review-markup layers and must be reserved for intentional markup in\nopen canvas space. Reserve arrows for a note that must point at one specific\ncontrol inside a frame; a note that simply sits beside its frame needs no arrow.\n\n**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`\n(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,\n`replace-blocks`, `update-canvas-annotation`) rather\nthan regenerating the whole plan. `contentPatches` are part of the public MCP\naction schema, so Claude Code, Codex, Cursor, and other hosts can make surgical\nedits. If an agent is working from exported source files, use\n`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds\nfrontmatter plus markdown/document blocks, `canvas.mdx` holds\n`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the\npatch action normalizes the MDX back into the same JSON runtime model. JSON is\nthe canonical runtime shape; MDX is the repo-friendly authoring/export surface.\nIn the browser, humans edit `rich-text` prose inline; agents should still use\n`update-rich-text` content patches or source patches for prose, and use\ncomments/structured patches for canvas, artboard, wireframe, and diagram edits.\nNever send a partial top-level `content` object as a shortcut to add a canvas,\nframe, or block: `content` is a full structured replacement, so omitted blocks\nor surfaces can disappear. If a full replacement is truly unavoidable, read the\ncomplete source/JSON first, include every existing block and surface in the new\npayload, and verify the source/export immediately after the update.\n\n**Never emit a titled artboard with no interior wireframe content.** Every artboard\nyou place on the canvas must carry an `html` wireframe or reference a wireframe\nblock via `blockId`; when using `blockId`, the referenced `wireframe` /\n`legacy-wireframe` block must remain in the plan. If you remove a duplicate\nwireframe from the document body, first move its `data` inline onto the\ncorresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A\nlabel-only frame or a frame pointing at a deleted block renders empty and is\nrejected at parse time. If you only have a title, write it as a section header or\nannotation, not an empty artboard.\n\n**UI mockups belong in the top visual review area.** Static UI/product visuals\nlive on the canvas; multi-step UI flows get both canvas wireframes and a\nprototype. When the user asks for a mockup, UI state, loading state, layout,\nscreen, or visual comparison, make the canvas the primary home for that static\nvisual. When the user asks for a prototype or the plan contains a sequence the\nreviewer must feel, keep the canvas artboards and add `content.prototype` so the\ntop surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay\ninline in the document (the SKILL.md Visual Surface Choice section owns that\nrule) unless the user explicitly asks for a spatial board. Document blocks\ncan explain, compare, or map implementation, but they should not host the\nprimary UI mockup or prototype just because `custom-html`, screenshots, or prose\nare easier to produce. If the canvas/prototype surface cannot represent the\nrequested UI fidelity, still keep the closest top-surface representation and\ncall out or extend the needed renderer capability. A skeleton/loading mockup\nalso lives in a canvas artboard \u2014 never move a mockup out of the canvas.\n\n**Storyboards are canvas artifacts, not document diagrams.** When the requested\noutput is a product flow, onboarding journey, \"light storyboard\", or canvas\nwireframe, author the flow as multiple top-canvas artboards with real screen\ncontent and neighboring connectors. Keep document-body `diagram` blocks for\narchitecture and mechanics that are not themselves user-visible screens. A\nstoryboard made from a single inline HTML diagram is the wrong surface.\n\nFor abstract product concepts, use the canvas to create the first \"I get it\"\nmoment: one real app state near the top showing how the concept appears to a\nuser, followed by separate annotations or diagrams for mechanics. Do not make\nthe first artboard a hybrid of app UI and architecture notes; the app screen\nshould be inspectable as product UI on its own.\n\n**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit\nnodes instead of `html`; the renderer still accepts and displays it so saved\nplans round-trip, but new plans emit `html`. Do not author fresh kit-tree\nscreens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,\n`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard\nwith kit-tree children is a defect: replace it with\n`<Screen surface=\"...\" html={...} />` using the HTML wireframe rules. The HTML\npath is the one that gets the renderer-owned surface sizing, theme tokens,\nsketch/clean toggle, and safe text layout used by good document-body\nwireframes. Likewise, old or imported plans may carry coordinate-based regions\nor free-float x/y on notes; those are legacy escape hatches the renderer still\nshows but you must never produce. The gutter parks notes by `targetId` +\n`placement`, and the coordinate rule at the top of this file governs all\nnew-plan placement.\n\n<!-- SHARED-CORE:canvas-surface END -->";
+export declare const CANVAS_REFERENCE_MD = "# Canvas & artboard placement \u2014 single source of truth\n\nThis file is the canonical guide for how the visual-plan canvas works: artboard\nplacement, lane layout, annotations, patching, and the legacy kit tree. Read it\nin full before authoring or editing any canvas/artboard content; do not author\ncanvas layouts from memory or paraphrase these rules per mode.\n\n<!-- SHARED-CORE:canvas-surface START -->\n\n**The coordinate rule.** The `surface` locks each artboard's footprint and\naspect \u2014 never set artboard width/height and never use coordinates inside the\nwireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear\nlanes. Let canvas auto-placement handle simple one-row boards.\n\n**Lay out mixed canvases in lanes.** When a canvas contains broad browser /\ndesktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put\neverything in one horizontal strip. Use board-level artboard `x`/`y` to reserve\nlanes with generous empty space: main flow on one row, compact surfaces in their\nown column or row, and loading/error states in a lower row. Keep at least 96px\nbetween rendered artboard rectangles plus room for annotation gutters; when a\nbroad browser/desktop frame sits beside a compact panel/popover, leave at least\n160px so frame borders, labels, and hover controls never touch. Connect only\nneighboring steps; never draw a long connector that skips across unrelated\nframes. Connector labels must sit in open canvas space. If the label would touch\nor cross either artboard, remove the label and explain the transition with a\nnearby annotation instead. Before handoff, inspect the top canvas at default zoom\nand move any frame whose label, connector, or annotation crosses another frame.\n\n**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. `browser` frames occupy roughly 700 \u00D7 600 board units; `desktop` frames roughly 900 \u00D7 700 board units. Apply these minimum x/y gaps when placing frames explicitly \u2014 any less and frames will touch or overlap:\n\n- x-gap between `browser` frames: **\u2265 1100** (700-unit frame + 400-unit gutter)\n- x-gap between `desktop` frames: **\u2265 1300** (900-unit frame + 400-unit gutter)\n- y-gap between rows of any surface: **\u2265 1400** (includes frame height + section header + buffer)\n\nWhen in doubt, use larger values \u2014 the canvas auto-zooms to fit everything.\n\n**Canvas annotations are designer notes on the artboard.** When a top canvas is\npresent, sprinkle design-review notes near the frames they explain: a short\nheading, supporting text, and bullets \u2014 plain text layers, never bordered or\nshadowed cards, and never a box around a frame. The renderer spaces notes away\nfrom frames, so place each note by the frame it describes. Use an arrow only to\npoint at one specific control or transition; for a broad frame-level note, write\ntext beside the frame with no connector. Connectors are for real sequences only \u2014\nnever fake \"Step 1 \u2192 Step 2\" lines between independent states.\n\n**Do not create overlapping annotations.** Anchor each ordinary note to the\nframe it explains with `targetId` + `placement` (top/right/bottom/left), and\nomit `type` or use `type: \"note\"`. The renderer parks notes in a gutter beside\nthe frame and lays them out automatically. Do not use `type: \"callout\"`,\n`type: \"text\"`, `type: \"arrow\"`, x/y, or points for ordinary notes; those are\nfreeform review-markup layers and must be reserved for intentional markup in\nopen canvas space. Reserve arrows for a note that must point at one specific\ncontrol inside a frame; a note that simply sits beside its frame needs no arrow.\n\n**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`\n(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,\n`replace-blocks`, `update-canvas-annotation`) rather\nthan regenerating the whole plan. `contentPatches` are part of the public MCP\naction schema, so Claude Code, Codex, Cursor, and other hosts can make surgical\nedits. If an agent is working from exported source files, use\n`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds\nfrontmatter plus markdown/document blocks, `canvas.mdx` holds\n`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the\npatch action normalizes the MDX back into the same JSON runtime model. JSON is\nthe canonical runtime shape; MDX is the repo-friendly authoring/export surface.\nIn the browser, humans edit `rich-text` prose inline; agents should still use\n`update-rich-text` content patches or source patches for prose, and use\ncomments/structured patches for canvas, artboard, wireframe, and diagram edits.\nNever send a partial top-level `content` object as a shortcut to add a canvas,\nframe, or block: `content` is a full structured replacement, so omitted blocks\nor surfaces can disappear. If a full replacement is truly unavoidable, read the\ncomplete source/JSON first, include every existing block and surface in the new\npayload, and verify the source/export immediately after the update.\n\n**Never emit a titled artboard with no interior wireframe content.** Every artboard\nyou place on the canvas must carry an `html` wireframe or reference a wireframe\nblock via `blockId`; when using `blockId`, the referenced `wireframe` /\n`legacy-wireframe` block must remain in the plan. If you remove a duplicate\nwireframe from the document body, first move its `data` inline onto the\ncorresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A\nlabel-only frame or a frame pointing at a deleted block renders empty and is\nrejected at parse time. If you only have a title, write it as a section header or\nannotation, not an empty artboard.\n\n**UI mockups belong in the top visual review area.** Static UI/product visuals\nlive on the canvas; multi-step UI flows get both canvas wireframes and a\nprototype. When the user asks for a mockup, UI state, loading state, layout,\nscreen, or visual comparison, make the canvas the primary home for that static\nvisual. When the user asks for a prototype or the plan contains a sequence the\nreviewer must feel, keep the canvas artboards and add `content.prototype` so the\ntop surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay\ninline in the document (the SKILL.md Visual Surface Choice section owns that\nrule) unless the user explicitly asks for a spatial board. Document blocks\ncan explain, compare, or map implementation, but they should not host the\nprimary UI mockup or prototype just because `custom-html`, screenshots, or prose\nare easier to produce. If the canvas/prototype surface cannot represent the\nrequested UI fidelity, still keep the closest top-surface representation and\ncall out or extend the needed renderer capability. A skeleton/loading mockup\nalso lives in a canvas artboard \u2014 never move a mockup out of the canvas.\n\n**Storyboards are canvas artifacts, not document diagrams.** When the requested\noutput is a product flow, onboarding journey, \"light storyboard\", or canvas\nwireframe, author the flow as multiple top-canvas artboards with real screen\ncontent and neighboring connectors. Keep document-body `diagram` blocks for\narchitecture and mechanics that are not themselves user-visible screens. A\nstoryboard made from a single inline HTML diagram is the wrong surface.\n\nFor abstract product concepts, use the canvas to create the first \"I get it\"\nmoment: one real app state near the top showing how the concept appears to a\nuser, followed by separate annotations or diagrams for mechanics. Do not make\nthe first artboard a hybrid of app UI and architecture notes; the app screen\nshould be inspectable as product UI on its own.\n\n**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit\nnodes instead of `html`; the renderer still accepts and displays it so saved\nplans round-trip, but new plans emit `html`. Do not author fresh kit-tree\nscreens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,\n`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard\nwith kit-tree children is a defect: replace it with\n`<Screen surface=\"...\" html={...} />` using the HTML wireframe rules. The HTML\npath is the one that gets the renderer-owned surface sizing, theme tokens,\nsketch/clean toggle, and safe text layout used by good document-body\nwireframes. Likewise, old or imported plans may carry coordinate-based regions\nor free-float x/y on notes; those are legacy escape hatches the renderer still\nshows but you must never produce. The gutter parks notes by `targetId` +\n`placement`, and the coordinate rule at the top of this file governs all\nnew-plan placement.\n\n<!-- SHARED-CORE:canvas-surface END -->\n";
+export declare const CANVAS_REFERENCE_POINTER = "The canvas is the single source of truth for static UI mockups: the `surface`\nlocks each artboard's footprint, mixed surfaces lay out\nin lanes, annotations are plain-text designer notes anchored by\n`targetId`/`placement`, and edits are surgical `contentPatches`. Before\nauthoring or editing ANY canvas, artboard, or annotation, READ\n`references/canvas.md` in this skill directory \u2014 it is the single source of truth\nfor canvas/artboard mechanics. Do not author canvas layouts from memory.";
+//# sourceMappingURL=canvas.d.ts.map

package/dist/cli/skills-content/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../../src/cli/skills-content/canvas.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,m3QAyHQ,CAAC;AASzC,eAAO,MAAM,mBAAmB,wuRAQ/B,CAAC;AAMF,eAAO,MAAM,wBAAwB,ufAMoC,CAAC"}

package/dist/cli/skills-content/canvas.js

@@ -0,0 +1,152 @@
+// Canvas/artboard placement mechanics. Used only by visual-plan modes
+// (visual-recap renders standalone wireframes, not a canvas).
+export const CANVAS_SURFACE_CORE = `<!-- 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.
+
+**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. \`browser\` frames occupy roughly 700 × 600 board units; \`desktop\` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:
+
+- x-gap between \`browser\` frames: **≥ 1100** (700-unit frame + 400-unit gutter)
+- x-gap between \`desktop\` frames: **≥ 1300** (900-unit frame + 400-unit gutter)
+- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)
+
+When in doubt, use larger values — the canvas auto-zooms to fit everything.
+
+**Canvas annotations are designer notes on the artboard.** When a top canvas is
+present, sprinkle design-review 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 -->`;
+// Progressive-disclosure reference files. Like `WIREFRAME_REFERENCE_MD`, each of
+// the canvas / document-quality / exemplar cores is the single source of truth
+// for its topic and is materialized verbatim into a sibling `references/*.md`
+// file in the visual-plan skill dir instead of being interpolated inline into
+// the SKILL.md body. The body carries only the matching `*_REFERENCE_POINTER`.
+// Keeping each reference body byte-identical to its core (markers included) lets
+// the sync guard assert the on-disk copies never drift from the constant.
+export const CANVAS_REFERENCE_MD = `# 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.
+
+${CANVAS_SURFACE_CORE}
+`;
+// Short pointers that replace the inline canvas / document-quality / exemplar
+// cores in the SKILL.md body. Authoring detail lives in the sibling reference
+// files so the SKILL.md stays lean (progressive disclosure); the agent loads the
+// detail on demand.
+export const CANVAS_REFERENCE_POINTER = `The canvas is the single source of truth for static UI mockups: the \`surface\`
+locks each artboard's footprint, mixed surfaces lay out
+in lanes, annotations are plain-text designer notes anchored by
+\`targetId\`/\`placement\`, and edits are surgical \`contentPatches\`. Before
+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.`;
+//# sourceMappingURL=canvas.js.map

package/dist/cli/skills-content/canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../../../src/cli/skills-content/canvas.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAyHK,CAAC;AAEzC,iFAAiF;AACjF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,iFAAiF;AACjF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;EAOjC,mBAAmB;CACpB,CAAC;AAEF,8EAA8E;AAC9E,8EAA8E;AAC9E,iFAAiF;AACjF,oBAAoB;AACpB,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;yEAMiC,CAAC","sourcesContent":["// Canvas/artboard placement mechanics. Used only by visual-plan modes\n// (visual-recap renders standalone wireframes, not a canvas).\nexport const CANVAS_SURFACE_CORE = `<!-- SHARED-CORE:canvas-surface START -->\n\n**The coordinate rule.** The \\`surface\\` locks each artboard's footprint and\naspect — never set artboard width/height and never use coordinates inside the\nwireframe HTML; board-level artboard \\`x\\`/\\`y\\` IS allowed when it creates clear\nlanes. Let canvas auto-placement handle simple one-row boards.\n\n**Lay out mixed canvases in lanes.** When a canvas contains broad browser /\ndesktop frames plus compact \\`mobile\\`, \\`popover\\`, or \\`panel\\` surfaces, do not put\neverything in one horizontal strip. Use board-level artboard \\`x\\`/\\`y\\` to reserve\nlanes with generous empty space: main flow on one row, compact surfaces in their\nown column or row, and loading/error states in a lower row. Keep at least 96px\nbetween rendered artboard rectangles plus room for annotation gutters; when a\nbroad browser/desktop frame sits beside a compact panel/popover, leave at least\n160px so frame borders, labels, and hover controls never touch. Connect only\nneighboring steps; never draw a long connector that skips across unrelated\nframes. Connector labels must sit in open canvas space. If the label would touch\nor cross either artboard, remove the label and explain the transition with a\nnearby annotation instead. Before handoff, inspect the top canvas at default zoom\nand move any frame whose label, connector, or annotation crosses another frame.\n\n**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. \\`browser\\` frames occupy roughly 700 × 600 board units; \\`desktop\\` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:\n\n- x-gap between \\`browser\\` frames: **≥ 1100** (700-unit frame + 400-unit gutter)\n- x-gap between \\`desktop\\` frames: **≥ 1300** (900-unit frame + 400-unit gutter)\n- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)\n\nWhen in doubt, use larger values — the canvas auto-zooms to fit everything.\n\n**Canvas annotations are designer notes on the artboard.** When a top canvas is\npresent, sprinkle design-review notes near the frames they explain: a short\nheading, supporting text, and bullets — plain text layers, never bordered or\nshadowed cards, and never a box around a frame. The renderer spaces notes away\nfrom frames, so place each note by the frame it describes. Use an arrow only to\npoint at one specific control or transition; for a broad frame-level note, write\ntext beside the frame with no connector. Connectors are for real sequences only —\nnever fake \"Step 1 → Step 2\" lines between independent states.\n\n**Do not create overlapping annotations.** Anchor each ordinary note to the\nframe it explains with \\`targetId\\` + \\`placement\\` (top/right/bottom/left), and\nomit \\`type\\` or use \\`type: \"note\"\\`. The renderer parks notes in a gutter beside\nthe frame and lays them out automatically. Do not use \\`type: \"callout\"\\`,\n\\`type: \"text\"\\`, \\`type: \"arrow\"\\`, x/y, or points for ordinary notes; those are\nfreeform review-markup layers and must be reserved for intentional markup in\nopen canvas space. Reserve arrows for a note that must point at one specific\ncontrol inside a frame; a note that simply sits beside its frame needs no arrow.\n\n**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted \\`contentPatches\\`\n(for example \\`patch-wireframe-html\\`, \\`patch-diagram-html\\`, \\`update-block\\`,\n\\`replace-blocks\\`, \\`update-canvas-annotation\\`) rather\nthan regenerating the whole plan. \\`contentPatches\\` are part of the public MCP\naction schema, so Claude Code, Codex, Cursor, and other hosts can make surgical\nedits. If an agent is working from exported source files, use\n\\`read-visual-plan-source\\` / \\`patch-visual-plan-source\\`: \\`plan.mdx\\` holds\nfrontmatter plus markdown/document blocks, \\`canvas.mdx\\` holds\n\\`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>\\`, and the\npatch action normalizes the MDX back into the same JSON runtime model. JSON is\nthe canonical runtime shape; MDX is the repo-friendly authoring/export surface.\nIn the browser, humans edit \\`rich-text\\` prose inline; agents should still use\n\\`update-rich-text\\` content patches or source patches for prose, and use\ncomments/structured patches for canvas, artboard, wireframe, and diagram edits.\nNever send a partial top-level \\`content\\` object as a shortcut to add a canvas,\nframe, or block: \\`content\\` is a full structured replacement, so omitted blocks\nor surfaces can disappear. If a full replacement is truly unavoidable, read the\ncomplete source/JSON first, include every existing block and surface in the new\npayload, and verify the source/export immediately after the update.\n\n**Never emit a titled artboard with no interior wireframe content.** Every artboard\nyou place on the canvas must carry an \\`html\\` wireframe or reference a wireframe\nblock via \\`blockId\\`; when using \\`blockId\\`, the referenced \\`wireframe\\` /\n\\`legacy-wireframe\\` block must remain in the plan. If you remove a duplicate\nwireframe from the document body, first move its \\`data\\` inline onto the\ncorresponding \\`content.canvas.frames[*].wireframe\\` / \\`legacyWireframe\\`. A\nlabel-only frame or a frame pointing at a deleted block renders empty and is\nrejected at parse time. If you only have a title, write it as a section header or\nannotation, not an empty artboard.\n\n**UI mockups belong in the top visual review area.** Static UI/product visuals\nlive on the canvas; multi-step UI flows get both canvas wireframes and a\nprototype. When the user asks for a mockup, UI state, loading state, layout,\nscreen, or visual comparison, make the canvas the primary home for that static\nvisual. When the user asks for a prototype or the plan contains a sequence the\nreviewer must feel, keep the canvas artboards and add \\`content.prototype\\` so the\ntop surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay\ninline in the document (the SKILL.md Visual Surface Choice section owns that\nrule) unless the user explicitly asks for a spatial board. Document blocks\ncan explain, compare, or map implementation, but they should not host the\nprimary UI mockup or prototype just because \\`custom-html\\`, screenshots, or prose\nare easier to produce. If the canvas/prototype surface cannot represent the\nrequested UI fidelity, still keep the closest top-surface representation and\ncall out or extend the needed renderer capability. A skeleton/loading mockup\nalso lives in a canvas artboard — never move a mockup out of the canvas.\n\n**Storyboards are canvas artifacts, not document diagrams.** When the requested\noutput is a product flow, onboarding journey, \"light storyboard\", or canvas\nwireframe, author the flow as multiple top-canvas artboards with real screen\ncontent and neighboring connectors. Keep document-body \\`diagram\\` blocks for\narchitecture and mechanics that are not themselves user-visible screens. A\nstoryboard made from a single inline HTML diagram is the wrong surface.\n\nFor abstract product concepts, use the canvas to create the first \"I get it\"\nmoment: one real app state near the top showing how the concept appears to a\nuser, followed by separate annotations or diagrams for mechanics. Do not make\nthe first artboard a hybrid of app UI and architecture notes; the app screen\nshould be inspectable as product UI on its own.\n\n**Legacy kit tree.** Older plans set a \\`screen\\` array of \\`{ el, ...props }\\` kit\nnodes instead of \\`html\\`; the renderer still accepts and displays it so saved\nplans round-trip, but new plans emit \\`html\\`. Do not author fresh kit-tree\nscreens, and do not put nested kit components such as \\`<FrameScreen>\\`, \\`<Card>\\`,\n\\`<Row>\\`, \\`<Title>\\`, or \\`<Btn>\\` inside a canvas \\`<Screen>\\`. A new canvas artboard\nwith kit-tree children is a defect: replace it with\n\\`<Screen surface=\"...\" html={...} />\\` using the HTML wireframe rules. The HTML\npath is the one that gets the renderer-owned surface sizing, theme tokens,\nsketch/clean toggle, and safe text layout used by good document-body\nwireframes. Likewise, old or imported plans may carry coordinate-based regions\nor free-float x/y on notes; those are legacy escape hatches the renderer still\nshows but you must never produce. The gutter parks notes by \\`targetId\\` +\n\\`placement\\`, and the coordinate rule at the top of this file governs all\nnew-plan placement.\n\n<!-- SHARED-CORE:canvas-surface END -->`;\n\n// Progressive-disclosure reference files. Like `WIREFRAME_REFERENCE_MD`, each of\n// the canvas / document-quality / exemplar cores is the single source of truth\n// for its topic and is materialized verbatim into a sibling `references/*.md`\n// file in the visual-plan skill dir instead of being interpolated inline into\n// the SKILL.md body. The body carries only the matching `*_REFERENCE_POINTER`.\n// Keeping each reference body byte-identical to its core (markers included) lets\n// the sync guard assert the on-disk copies never drift from the constant.\nexport const CANVAS_REFERENCE_MD = `# Canvas & artboard placement — single source of truth\n\nThis file is the canonical guide for how the visual-plan canvas works: artboard\nplacement, lane layout, annotations, patching, and the legacy kit tree. Read it\nin full before authoring or editing any canvas/artboard content; do not author\ncanvas layouts from memory or paraphrase these rules per mode.\n\n${CANVAS_SURFACE_CORE}\n`;\n\n// Short pointers that replace the inline canvas / document-quality / exemplar\n// cores in the SKILL.md body. Authoring detail lives in the sibling reference\n// files so the SKILL.md stays lean (progressive disclosure); the agent loads the\n// detail on demand.\nexport const CANVAS_REFERENCE_POINTER = `The canvas is the single source of truth for static UI mockups: the \\`surface\\`\nlocks each artboard's footprint, mixed surfaces lay out\nin lanes, annotations are plain-text designer notes anchored by\n\\`targetId\\`/\\`placement\\`, and edits are surgical \\`contentPatches\\`. Before\nauthoring or editing ANY canvas, artboard, or annotation, READ\n\\`references/canvas.md\\` in this skill directory — it is the single source of truth\nfor canvas/artboard mechanics. Do not author canvas layouts from memory.`;\n"]}

package/dist/cli/skills-content/connection.d.ts

@@ -0,0 +1,2 @@
+export declare const CONNECTION_REFERENCE_MD = "# Connecting & publishing \u2014 single source of truth\n\nThis file is the canonical rule for the never-inline deliverable, finding the\nPlan MCP connector, and restoring it when its tools are missing. It is shared\nword for word by `/visual-plan` and `/visual-recap`. Read it when you are about\nto publish, or whenever a connector or auth error appears; do not improvise an\ninline fallback from memory.\n\n<!-- SHARED-CORE:connection START -->\n\n**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat\ncontent.** Do not hand the plan or recap to the user as Markdown prose, an ASCII\nsketch, a table, a fenced \"wireframe\", or a \"here's the summary\" paragraph. The\nentire value is the hosted, interactive, annotatable Plan; an inline summary is\nthe thing a Plan replaces, not a degraded version of one. The only supported\noutput is to publish through the Plan MCP connector and return its absolute URL.\nLocal-files privacy mode (`references/local-files.md`) is the one exception.\n\n**The connector is usually the `plan` server**, but older installed agents may\nexpose the same hosted connector as `agent-native-plans` \u2014 both names are valid,\nso never report the connector as missing just because it is named\n`agent-native-plans` instead of `plan`. Some clients also lazy-load connector\ntools through a deferred tool registry instead of showing the namespace upfront.\nBefore declaring the connector missing, search/load tools with the host's\ndiscovery surface (`tool_search` when available) for `create_visual_plan`,\n`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.\n\n**If the tools are still missing after discovery, do NOT fall back to inline\noutput.** The usual cause is a connector that did not finish connecting this\nsession (it registers zero tools), NOT necessarily an auth problem \u2014 so do not\nassume the user must re-authenticate. Stop and give the user the exact restore\nstep for their current client:\n\n- **Codex / Codex Desktop:** run\n  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`\n  and start a new Codex session.\n- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same\n  reconnect command with `--client claude-code` and restart Claude.\n\nThe same applies when a Plan tool returns `needs auth`, `Unauthorized`, or\n`Session terminated`: stop retrying the tool and give the reconnect step instead.\n\nAuth is stored per client config/session, so one client's reconnect does not make\nanother running client load tools. `--client all` refreshes every local client\nconfig that already has the Plan entry, but each running client still has to\nreload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling\nand finds the entry by URL regardless of connector name \u2014 never reinstall from\nscratch just to fix auth. Publish once the tool is reachable. Falling back to\ninline content is a defect, not a degraded mode.\n\n<!-- SHARED-CORE:connection END -->\n";
+//# sourceMappingURL=connection.d.ts.map

package/dist/cli/skills-content/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/cli/skills-content/connection.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,4+FAmDnC,CAAC"}

package/dist/cli/skills-content/connection.js

@@ -0,0 +1,53 @@
+export const CONNECTION_REFERENCE_MD = `# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by \`/visual-plan\` and \`/visual-recap\`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (\`references/local-files.md\`) is the one exception.
+
+**The connector is usually the \`plan\` server**, but older installed agents may
+expose the same hosted connector as \`agent-native-plans\` — both names are valid,
+so never report the connector as missing just because it is named
+\`agent-native-plans\` instead of \`plan\`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (\`tool_search\` when available) for \`create_visual_plan\`,
+\`create_visual_recap\`, or \`get_plan_blocks\`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** The usual cause is a connector that did not finish connecting this
+session (it registers zero tools), NOT necessarily an auth problem — so do not
+assume the user must re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  \`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\`
+  and start a new Codex session.
+- **Claude Code:** run \`/mcp\` and choose Authenticate/Reconnect, or run the same
+  reconnect command with \`--client claude-code\` and restart Claude.
+
+The same applies when a Plan tool returns \`needs auth\`, \`Unauthorized\`, or
+\`Session terminated\`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. \`--client all\` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->
+`;
+//# sourceMappingURL=connection.js.map

package/dist/cli/skills-content/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/cli/skills-content/connection.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDtC,CAAC","sourcesContent":["export const CONNECTION_REFERENCE_MD = `# Connecting & publishing — single source of truth\n\nThis file is the canonical rule for the never-inline deliverable, finding the\nPlan MCP connector, and restoring it when its tools are missing. It is shared\nword for word by \\`/visual-plan\\` and \\`/visual-recap\\`. Read it when you are about\nto publish, or whenever a connector or auth error appears; do not improvise an\ninline fallback from memory.\n\n<!-- SHARED-CORE:connection START -->\n\n**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat\ncontent.** Do not hand the plan or recap to the user as Markdown prose, an ASCII\nsketch, a table, a fenced \"wireframe\", or a \"here's the summary\" paragraph. The\nentire value is the hosted, interactive, annotatable Plan; an inline summary is\nthe thing a Plan replaces, not a degraded version of one. The only supported\noutput is to publish through the Plan MCP connector and return its absolute URL.\nLocal-files privacy mode (\\`references/local-files.md\\`) is the one exception.\n\n**The connector is usually the \\`plan\\` server**, but older installed agents may\nexpose the same hosted connector as \\`agent-native-plans\\` — both names are valid,\nso never report the connector as missing just because it is named\n\\`agent-native-plans\\` instead of \\`plan\\`. Some clients also lazy-load connector\ntools through a deferred tool registry instead of showing the namespace upfront.\nBefore declaring the connector missing, search/load tools with the host's\ndiscovery surface (\\`tool_search\\` when available) for \\`create_visual_plan\\`,\n\\`create_visual_recap\\`, or \\`get_plan_blocks\\`, then use the tools it exposes.\n\n**If the tools are still missing after discovery, do NOT fall back to inline\noutput.** The usual cause is a connector that did not finish connecting this\nsession (it registers zero tools), NOT necessarily an auth problem — so do not\nassume the user must re-authenticate. Stop and give the user the exact restore\nstep for their current client:\n\n- **Codex / Codex Desktop:** run\n  \\`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex\\`\n  and start a new Codex session.\n- **Claude Code:** run \\`/mcp\\` and choose Authenticate/Reconnect, or run the same\n  reconnect command with \\`--client claude-code\\` and restart Claude.\n\nThe same applies when a Plan tool returns \\`needs auth\\`, \\`Unauthorized\\`, or\n\\`Session terminated\\`: stop retrying the tool and give the reconnect step instead.\n\nAuth is stored per client config/session, so one client's reconnect does not make\nanother running client load tools. \\`--client all\\` refreshes every local client\nconfig that already has the Plan entry, but each running client still has to\nreload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling\nand finds the entry by URL regardless of connector name — never reinstall from\nscratch just to fix auth. Publish once the tool is reachable. Falling back to\ninline content is a defect, not a degraded mode.\n\n<!-- SHARED-CORE:connection END -->\n`;\n"]}

package/dist/cli/skills-content/content-skill.d.ts

@@ -0,0 +1,2 @@
+export declare const CONTENT_SKILL_MD = "---\nname: content\ndescription: >-\n  Use Content for repo-backed Markdown/MDX docs, blogs, resources, rich\n  document editing, local components, shareable copies, and Content local-file\n  workspaces. Prefer Content actions over raw filesystem writes when available.\nmetadata:\n  visibility: exported\n---\n\n# Content\n\nUse the Content app when a workflow is about authoring, editing, reviewing, or\npublishing Markdown/MDX documents: docs sites, blogs, resource libraries,\nmarketing pages, internal notes, and local MDX components. Content gives the\nagent a document tree, a rich editor, normal document actions, and optional\nlocal-file source of truth.\n\n## Choose The Path\n\n- Use Content actions when the Content MCP/action tools are available:\n  `list-documents`, `search-documents`, `get-document`,\n  `pull-document`, `create-document`, `edit-document`,\n  `update-document`, `delete-document`, `share-local-file-document`,\n  `list-local-component-files`, and `write-local-component-file`.\n- Use `pull-document` or `get-document` before editing a page. Use\n  `edit-document` for precise find/replace changes and `update-document`\n  for full rewrites or new content.\n- In Local File Mode, Content actions read and write the repo files declared in\n  `agent-native.json`; SQL remains cache/history/search glue, not the source of\n  truth for those pages.\n- If Content tools are not visible and no local Content app or Desktop bridge is\n  running, treat this skill as repo-editing guidance. Edit configured\n  `.md`/`.mdx` files directly, preserve frontmatter and MDX imports, and tell\n  the user the Content action surface was not available.\n\n## Action Examples\n\nPrefer JSON input for action calls:\n\n```bash\npnpm action list-documents\npnpm action get-document '{\"id\":\"local-file:...\"}'\npnpm action edit-document '{\"id\":\"local-file:...\",\"find\":\"old copy\",\"replace\":\"new copy\"}'\npnpm action update-document '{\"id\":\"local-file:...\",\"content\":\"# Updated\\n\\nBody\"}'\npnpm action share-local-file-document '{\"id\":\"local-file:...\"}'\n```\n\nRun `refresh-list` after create/update/delete operations when you need the\nopen Content UI sidebar to repaint immediately.\n\n## Local File Mode\n\nInstall into an existing repo with:\n\n```bash\nnpx @agent-native/core@latest skills add content --mode local-files --scope project\n```\n\nThe installer copies this skill and writes or updates `agent-native.json` with\nContent roots for `docs/`, `blog/`, `content/`, and `resources/`, plus a\n`components/` folder for local MDX components. A typical manifest looks like:\n\n```json\n{\n  \"version\": 1,\n  \"apps\": {\n    \"content\": {\n      \"mode\": \"local-files\",\n      \"roots\": [\n        { \"name\": \"Docs\", \"path\": \"docs\", \"kind\": \"docs\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Blog\", \"path\": \"blog\", \"kind\": \"blog\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Content\", \"path\": \"content\", \"kind\": \"content\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Resources\", \"path\": \"resources\", \"kind\": \"resources\", \"extensions\": [\".md\", \".mdx\"] }\n      ],\n      \"components\": \"components\",\n      \"extensions\": \"extensions\",\n      \"hide\": [\"**/_*.md\", \"**/_*.mdx\"]\n    }\n  }\n}\n```\n\nLocal File Mode does not make the host language model local, and the hosted\nContent app cannot read private repo files by itself. File access requires a\nlocal Content app, Agent Native Desktop, or another trusted local bridge.\n\n## MDX And Components\n\n- Preserve frontmatter keys you do not understand. Preserve MDX imports,\n  exports, JSX, and expression props unless the user explicitly asks to change\n  them.\n- Use local components from the configured `components` folder. Components\n  should be PascalCase exports from `.tsx` files; simple editable input metadata\n  can live next to them as `ComponentNameInputs`.\n- Use `list-local-component-files` and `write-local-component-file` for\n  component source changes when Content tools are available. Otherwise edit the\n  component files directly like normal repo source.\n\n## Boundaries\n\n- Moving, renaming, and reordering local-file pages are not first-class Content\n  UI operations yet. Use normal file operations when the user asks for those,\n  then let Content rediscover the file tree.\n- Do not push/pull Notion, Builder.io, or other provider-backed content unless\n  the user explicitly asks for provider sync.\n- Do not paste secrets, private provider data, or credential-looking values into\n  docs, generated pages, frontmatter, examples, or local components.\n";
+//# sourceMappingURL=content-skill.d.ts.map

package/dist/cli/skills-content/content-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-skill.d.ts","sourceRoot":"","sources":["../../../src/cli/skills-content/content-skill.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,omJA4G5B,CAAC"}

package/dist/cli/skills-content/content-skill.js

@@ -0,0 +1,110 @@
+export const CONTENT_SKILL_MD = `---
+name: content
+description: >-
+  Use Content for repo-backed Markdown/MDX docs, blogs, resources, rich
+  document editing, local components, shareable copies, and Content local-file
+  workspaces. Prefer Content actions over raw filesystem writes when available.
+metadata:
+  visibility: exported
+---
+
+# Content
+
+Use the Content app when a workflow is about authoring, editing, reviewing, or
+publishing Markdown/MDX documents: docs sites, blogs, resource libraries,
+marketing pages, internal notes, and local MDX components. Content gives the
+agent a document tree, a rich editor, normal document actions, and optional
+local-file source of truth.
+
+## Choose The Path
+
+- Use Content actions when the Content MCP/action tools are available:
+  \`list-documents\`, \`search-documents\`, \`get-document\`,
+  \`pull-document\`, \`create-document\`, \`edit-document\`,
+  \`update-document\`, \`delete-document\`, \`share-local-file-document\`,
+  \`list-local-component-files\`, and \`write-local-component-file\`.
+- Use \`pull-document\` or \`get-document\` before editing a page. Use
+  \`edit-document\` for precise find/replace changes and \`update-document\`
+  for full rewrites or new content.
+- In Local File Mode, Content actions read and write the repo files declared in
+  \`agent-native.json\`; SQL remains cache/history/search glue, not the source of
+  truth for those pages.
+- If Content tools are not visible and no local Content app or Desktop bridge is
+  running, treat this skill as repo-editing guidance. Edit configured
+  \`.md\`/\`.mdx\` files directly, preserve frontmatter and MDX imports, and tell
+  the user the Content action surface was not available.
+
+## Action Examples
+
+Prefer JSON input for action calls:
+
+\`\`\`bash
+pnpm action list-documents
+pnpm action get-document '{"id":"local-file:..."}'
+pnpm action edit-document '{"id":"local-file:...","find":"old copy","replace":"new copy"}'
+pnpm action update-document '{"id":"local-file:...","content":"# Updated\\n\\nBody"}'
+pnpm action share-local-file-document '{"id":"local-file:..."}'
+\`\`\`
+
+Run \`refresh-list\` after create/update/delete operations when you need the
+open Content UI sidebar to repaint immediately.
+
+## Local File Mode
+
+Install into an existing repo with:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+\`\`\`
+
+The installer copies this skill and writes or updates \`agent-native.json\` with
+Content roots for \`docs/\`, \`blog/\`, \`content/\`, and \`resources/\`, plus a
+\`components/\` folder for local MDX components. A typical manifest looks like:
+
+\`\`\`json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        { "name": "Docs", "path": "docs", "kind": "docs", "extensions": [".md", ".mdx"] },
+        { "name": "Blog", "path": "blog", "kind": "blog", "extensions": [".md", ".mdx"] },
+        { "name": "Content", "path": "content", "kind": "content", "extensions": [".md", ".mdx"] },
+        { "name": "Resources", "path": "resources", "kind": "resources", "extensions": [".md", ".mdx"] }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+\`\`\`
+
+Local File Mode does not make the host language model local, and the hosted
+Content app cannot read private repo files by itself. File access requires a
+local Content app, Agent Native Desktop, or another trusted local bridge.
+
+## MDX And Components
+
+- Preserve frontmatter keys you do not understand. Preserve MDX imports,
+  exports, JSX, and expression props unless the user explicitly asks to change
+  them.
+- Use local components from the configured \`components\` folder. Components
+  should be PascalCase exports from \`.tsx\` files; simple editable input metadata
+  can live next to them as \`ComponentNameInputs\`.
+- Use \`list-local-component-files\` and \`write-local-component-file\` for
+  component source changes when Content tools are available. Otherwise edit the
+  component files directly like normal repo source.
+
+## Boundaries
+
+- Moving, renaming, and reordering local-file pages are not first-class Content
+  UI operations yet. Use normal file operations when the user asks for those,
+  then let Content rediscover the file tree.
+- Do not push/pull Notion, Builder.io, or other provider-backed content unless
+  the user explicitly asks for provider sync.
+- Do not paste secrets, private provider data, or credential-looking values into
+  docs, generated pages, frontmatter, examples, or local components.
+`;
+//# sourceMappingURL=content-skill.js.map

package/dist/cli/skills-content/content-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-skill.js","sourceRoot":"","sources":["../../../src/cli/skills-content/content-skill.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4G/B,CAAC","sourcesContent":["export const CONTENT_SKILL_MD = `---\nname: content\ndescription: >-\n  Use Content for repo-backed Markdown/MDX docs, blogs, resources, rich\n  document editing, local components, shareable copies, and Content local-file\n  workspaces. Prefer Content actions over raw filesystem writes when available.\nmetadata:\n  visibility: exported\n---\n\n# Content\n\nUse the Content app when a workflow is about authoring, editing, reviewing, or\npublishing Markdown/MDX documents: docs sites, blogs, resource libraries,\nmarketing pages, internal notes, and local MDX components. Content gives the\nagent a document tree, a rich editor, normal document actions, and optional\nlocal-file source of truth.\n\n## Choose The Path\n\n- Use Content actions when the Content MCP/action tools are available:\n  \\`list-documents\\`, \\`search-documents\\`, \\`get-document\\`,\n  \\`pull-document\\`, \\`create-document\\`, \\`edit-document\\`,\n  \\`update-document\\`, \\`delete-document\\`, \\`share-local-file-document\\`,\n  \\`list-local-component-files\\`, and \\`write-local-component-file\\`.\n- Use \\`pull-document\\` or \\`get-document\\` before editing a page. Use\n  \\`edit-document\\` for precise find/replace changes and \\`update-document\\`\n  for full rewrites or new content.\n- In Local File Mode, Content actions read and write the repo files declared in\n  \\`agent-native.json\\`; SQL remains cache/history/search glue, not the source of\n  truth for those pages.\n- If Content tools are not visible and no local Content app or Desktop bridge is\n  running, treat this skill as repo-editing guidance. Edit configured\n  \\`.md\\`/\\`.mdx\\` files directly, preserve frontmatter and MDX imports, and tell\n  the user the Content action surface was not available.\n\n## Action Examples\n\nPrefer JSON input for action calls:\n\n\\`\\`\\`bash\npnpm action list-documents\npnpm action get-document '{\"id\":\"local-file:...\"}'\npnpm action edit-document '{\"id\":\"local-file:...\",\"find\":\"old copy\",\"replace\":\"new copy\"}'\npnpm action update-document '{\"id\":\"local-file:...\",\"content\":\"# Updated\\\\n\\\\nBody\"}'\npnpm action share-local-file-document '{\"id\":\"local-file:...\"}'\n\\`\\`\\`\n\nRun \\`refresh-list\\` after create/update/delete operations when you need the\nopen Content UI sidebar to repaint immediately.\n\n## Local File Mode\n\nInstall into an existing repo with:\n\n\\`\\`\\`bash\nnpx @agent-native/core@latest skills add content --mode local-files --scope project\n\\`\\`\\`\n\nThe installer copies this skill and writes or updates \\`agent-native.json\\` with\nContent roots for \\`docs/\\`, \\`blog/\\`, \\`content/\\`, and \\`resources/\\`, plus a\n\\`components/\\` folder for local MDX components. A typical manifest looks like:\n\n\\`\\`\\`json\n{\n  \"version\": 1,\n  \"apps\": {\n    \"content\": {\n      \"mode\": \"local-files\",\n      \"roots\": [\n        { \"name\": \"Docs\", \"path\": \"docs\", \"kind\": \"docs\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Blog\", \"path\": \"blog\", \"kind\": \"blog\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Content\", \"path\": \"content\", \"kind\": \"content\", \"extensions\": [\".md\", \".mdx\"] },\n        { \"name\": \"Resources\", \"path\": \"resources\", \"kind\": \"resources\", \"extensions\": [\".md\", \".mdx\"] }\n      ],\n      \"components\": \"components\",\n      \"extensions\": \"extensions\",\n      \"hide\": [\"**/_*.md\", \"**/_*.mdx\"]\n    }\n  }\n}\n\\`\\`\\`\n\nLocal File Mode does not make the host language model local, and the hosted\nContent app cannot read private repo files by itself. File access requires a\nlocal Content app, Agent Native Desktop, or another trusted local bridge.\n\n## MDX And Components\n\n- Preserve frontmatter keys you do not understand. Preserve MDX imports,\n  exports, JSX, and expression props unless the user explicitly asks to change\n  them.\n- Use local components from the configured \\`components\\` folder. Components\n  should be PascalCase exports from \\`.tsx\\` files; simple editable input metadata\n  can live next to them as \\`ComponentNameInputs\\`.\n- Use \\`list-local-component-files\\` and \\`write-local-component-file\\` for\n  component source changes when Content tools are available. Otherwise edit the\n  component files directly like normal repo source.\n\n## Boundaries\n\n- Moving, renaming, and reordering local-file pages are not first-class Content\n  UI operations yet. Use normal file operations when the user asks for those,\n  then let Content rediscover the file tree.\n- Do not push/pull Notion, Builder.io, or other provider-backed content unless\n  the user explicitly asks for provider sync.\n- Do not paste secrets, private provider data, or credential-looking values into\n  docs, generated pages, frontmatter, examples, or local components.\n`;\n"]}

package/dist/cli/skills-content/design-exploration-skill.d.ts

@@ -0,0 +1,2 @@
+export declare const DESIGN_EXPLORATION_SKILL_MD = "---\nname: design-exploration\ndescription: >-\n  Use Design for UI/UX exploration, side-by-side design directions,\n  interactive prototype previews, user selection, iteration, and design-to-code\n  handoff through the hosted Design MCP app.\nmetadata:\n  visibility: exported\n---\n\n# Design Exploration\n\nUse the Design app when a workflow needs visual UI exploration, prototype\niteration, or a human-in-the-loop choice among design directions.\n\n## Choose The Path\n\n- Use `create-design` first to create a project shell. Do not report the\n  design as ready until it has renderable HTML.\n- For open-ended UX exploration, generate distinct, compact, complete HTML\n  directions (2-5, three by default) and call `present-design-variants`. Each\n  direction should be one representative screen or directional snapshot, not a\n  full app per variant. Design saves every option as a normal screen on the\n  overview board and renders an inline chat choice with one button per screen\n  name. After the user picks, delete the unchosen variant screens and continue\n  from the kept screen by first calling `get-design-snapshot` with that\n  screen's `fileId`, then calling `edit-design` on that same `fileId` in a\n  bounded single-file pass. Use `mode: \"replace-file\"` when expanding the\n  representative placeholder into the full chosen direction. Do not call\n  `generate-design` after a variant pick.\n- If the chat choice buttons are not available in the host, ask the user to\n  tell you the screen name they prefer. The variants are already real screens\n  on the board, so do not ask them to paste HTML or copy a generated handoff\n  summary.\n- For direct refinements to an already chosen direction, call\n  `get-design-snapshot`, edit from the current tuned HTML, and use\n  `edit-design` for surgical changes or `mode: \"replace-file\"` for a bounded\n  selected-file replacement. Use `generate-design` for new files only.\n- Use `export-coding-handoff` when the user wants to implement the chosen\n  design in a codebase.\n\n## Exploration Defaults\n\n1. Default to three variants unless the user asks for a different count\n   (`present-design-variants` accepts 2-5; three is the sweet spot).\n2. Make variants structurally and stylistically distinct, not just color swaps.\n3. Each variant must be a compact, complete standalone HTML document that\n   renders without a build step.\n4. For product UI redesigns, prefer cleaner hierarchy, progressive disclosure,\n   and realistic controls over decorative mockups.\n5. After `present-design-variants`, wait for the user's pick before\n   generating the next version. Keep the chosen screen, delete the other\n   variant screens, call `get-design-snapshot` with `fileId` for the kept\n   screen, then call `edit-design` on that same `fileId` in a bounded pass.\n   Use `mode: \"replace-file\"` when expanding the representative placeholder\n   into the full chosen direction. Do not call `generate-design` after a\n   variant pick. Stop after the first successful `edit-design` save.\n\n## Design Quality Bar\n\nGeneric \"AI slop\" comes from letting one prompt set taste, explore, and emit code\nat once \u2014 so the model returns the training-average (Inter, an indigo/violet\ngradient, a centered hero, three rounded cards). The variant flow above exists to\nseparate those jobs; use it, and hold this bar:\n\n- Before generating, name the concrete audience, the screen's primary job, and\n  the visual thesis. If the brief is vague, make a reasonable choice and state\n  it instead of producing a generic dashboard/landing-page default.\n- Refuse the defaults, and pair every \"don't\" with a \"do\" (banning Inter alone\n  just makes you reach for Roboto). Avoid Inter/Roboto/system fonts, the\n  indigo/violet slop palette (`#6366F1`/`#8B5CF6`/`#A855F7`) and purple-on-white\n  gradients, and centered-hero + three-icon-card layouts; instead pick a\n  distinctive font pairing, one non-default palette family with a single decisive\n  accent, and an asymmetric layout with a clear focal point.\n- Make each direction distinct in structure and behavior, not just palette.\n  Give every variant one memorable signature choice, then keep the surrounding\n  chrome disciplined. Even your creative picks converge (Space Grotesk\n  everywhere) \u2014 vary deliberately so two directions never share a fingerprint.\n- For existing products, inspect the current screen, design system, tokens, and\n  component language before inventing a new direction. Treat any drift back to a\n  default as a missing token to pin, and vary layout per screen so on-brand does\n  not become same-in-your-colors.\n- Treat copy, data, and imagery as design material. Use realistic domain\n  content and first-party/generated assets when images matter; avoid lorem\n  ipsum, vague SaaS filler, and decorative placeholder boxes.\n- Build to a quiet quality floor: responsive desktop/mobile layout, visible\n  keyboard focus, useful loading/empty/error states for app UI, and reduced\n  motion support when custom motion is present.\n- After broad generation or refinement, inspect the rendered Design surface or\n  a screenshot-capable host before calling it ready. Fix obvious hierarchy,\n  overflow, contrast, broken interaction, and placeholder-content issues first.\n\n## Cross-App Use\n\n- Hosted default: connect `https://design.agent-native.com/_agent-native/mcp`.\n  Do not put shared secrets in skill files.\n- For CLI/code-editor clients, keep any `npx @agent-native/core@latest connect` command\n  running until browser authorization finishes. Stopping it early can leave the\n  browser approved but the local MCP config unwritten. Restart or reload the\n  agent client after installing or connecting if Design tools do not appear in\n  the live session.\n- Dispatch can expose Design alongside other apps. Use Design for UI/UX design\n  tasks, Assets for image/media selection, Slides for decks, and so on.\n- Keep the loop visual: surface the inline MCP App or the returned \"Open\n  design\" link instead of pasting large HTML blobs into chat.\n- If a Design tool call returns `Session terminated`, `needs auth`, or\n  another connector/session error, do not keep retrying the tool. Stop and give\n  the user the reconnect step: in Claude Code run `/mcp` and choose\n  Authenticate/Reconnect for the Design connector; from any terminal run\n  `npx -y @agent-native/core@latest reconnect https://design.agent-native.com` \u2014 this\n  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix\n  auth. Continue once the connector is available.\n- Do not hand-roll MCP HTTP requests with curl from the agent session. Use the\n  host-exposed Design tools after restart/reload, or use the returned\n  browser/deep-link fallback.\n- If you inspect local MCP config, redact `Authorization`, `http_headers`,\n  and token values. Never paste bearer tokens into chat or logs.\n";
+//# sourceMappingURL=design-exploration-skill.d.ts.map

package/dist/cli/skills-content/design-exploration-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-exploration-skill.d.ts","sourceRoot":"","sources":["../../../src/cli/skills-content/design-exploration-skill.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,8yNAqHvC,CAAC"}