@agent-native/core 0.140.0 → 0.141.1

package/dist/cli/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -1238,4 +1238,3 @@ Bugs:      ${BUGS_URL}`);
         console.error(`Bugs: ${BUGS_URL}`);
         process.exit(1);
 }
-//# sourceMappingURL=index.js.map

package/dist/cli/info.d.ts

@@ -1,2 +1 @@
 export declare function runInfo(pkgName?: string): void;
-//# sourceMappingURL=info.d.ts.map

package/dist/cli/info.js

@@ -100,4 +100,3 @@ function summarizeTarget(t) {
     }
     return String(t);
 }
-//# sourceMappingURL=info.js.map

package/dist/cli/invoke.d.ts

@@ -23,4 +23,3 @@ export declare function parseInvokeArgs(args: string[]): ParsedInvokeArgs;
 export declare function runInvoke(args: string[], io?: InvokeCliIo): Promise<number>;
 export declare function formatInvokeUsage(): string;
 export declare function inferSelfAppId(env?: NodeJS.ProcessEnv): string | undefined;
-//# sourceMappingURL=invoke.d.ts.map

package/dist/cli/invoke.js

@@ -224,4 +224,3 @@ function normalizeWorkspaceAppId(value) {
 function workspaceAppIdFromBasePath(value) {
     return normalizeWorkspaceAppId(value);
 }
-//# sourceMappingURL=invoke.js.map

package/dist/cli/mcp-config-writers.d.ts

@@ -120,4 +120,3 @@ export declare function removeCodexSameUrlDuplicates(file: string, mcpUrl: strin
  * Returns the list of removed names (empty if nothing was cleaned up).
  */
 export declare function removeSameUrlDuplicatesForClient(client: ClientId, serverName: string, mcpUrl: string, baseDir: string, scope: string | undefined): string[];
-//# sourceMappingURL=mcp-config-writers.d.ts.map

package/dist/cli/mcp-config-writers.js

@@ -719,4 +719,3 @@ export function removeSameUrlDuplicatesForClient(client, serverName, mcpUrl, bas
     }
     return removeJsonSameUrlDuplicatesAtKey(file, jsonMcpConfigKeyForClient(client), mcpUrl, serverName);
 }
-//# sourceMappingURL=mcp-config-writers.js.map

package/dist/cli/mcp.d.ts

@@ -27,4 +27,3 @@ export interface ScreenMemoryStoreResolutionOptions {
 export declare function resolveScreenMemoryStoreDir(options?: ScreenMemoryStoreResolutionOptions): string | undefined;
 export declare function installScreenMemoryForClient(client: ClientId, storeDir: string, cwd: string, scope: string | undefined): string;
 export declare function runMcp(args: string[]): Promise<void>;
-//# sourceMappingURL=mcp.d.ts.map

package/dist/cli/mcp.js

@@ -548,4 +548,3 @@ export async function runMcp(args) {
             process.exit(1);
     }
 }
-//# sourceMappingURL=mcp.js.map

package/dist/cli/migrate.d.ts

@@ -35,4 +35,3 @@ export declare function runMigrate(argv: string[]): Promise<void>;
 export declare function emitOwnAgentDossier(opts: MigrateCliOptions, cwd?: string): Promise<EmitDossierResult>;
 export declare function isExpectedMigrationCliError(error: unknown): boolean;
 export {};
-//# sourceMappingURL=migrate.d.ts.map

package/dist/cli/migrate.js

@@ -1490,4 +1490,3 @@ function shellQuote(value) {
 function toPosix(value) {
     return value.split(path.sep).join("/");
 }
-//# sourceMappingURL=migrate.js.map

package/dist/cli/migration-codemod.d.ts

@@ -19,4 +19,3 @@ export declare function loadMigrationManifests(projectRoot: string): MigrationMa
 export declare function createMigrationPlanningTargetResolver(projectRoot: string): (specifier: string, sourceFile?: string) => boolean;
 export declare function runMigrationCodemods(options: RunMigrationCodemodsOptions): MigrationCodemodResult;
 export declare function formatMigrationCodemodDiff(result: MigrationCodemodResult, root: string): string;
-//# sourceMappingURL=migration-codemod.d.ts.map

package/dist/cli/migration-codemod.js

@@ -415,4 +415,3 @@ export function formatMigrationCodemodDiff(result, root) {
         .map((change) => focusedDiff(change, path.resolve(root)))
         .join("\n");
 }
-//# sourceMappingURL=migration-codemod.js.map

package/dist/cli/multi-frontier-runs.d.ts

@@ -243,4 +243,3 @@ export declare function getMultiFrontierParticipantEventRetention(collaborationI
  * the newest contiguous tail and a replay marker instead of deleting run state.
  */
 export declare function compactMultiFrontierParticipantEvents(collaborationId: string, limits?: MultiFrontierParticipantEventRetentionLimits): MultiFrontierParticipantEventRetention | null;
-//# sourceMappingURL=multi-frontier-runs.d.ts.map

package/dist/cli/multi-frontier-runs.js

@@ -1244,4 +1244,3 @@ function assertTimestamp(value, label) {
         throw new Error(`Invalid multi-frontier ${label}.`);
     }
 }
-//# sourceMappingURL=multi-frontier-runs.js.map

package/dist/cli/package-lifecycle.d.ts

@@ -47,4 +47,3 @@ export declare function runPackageLifecycle(args: string[], runtime?: PackageLif
 export declare function packageLifecycleUsage(): string;
 export declare function loadLifecyclePackage(name: string, cwd: string, spawn?: typeof spawnSync): Promise<LoadedLifecyclePackage>;
 export {};
-//# sourceMappingURL=package-lifecycle.d.ts.map

package/dist/cli/package-lifecycle.js

@@ -559,4 +559,3 @@ function relative(root, file) {
     const value = path.relative(root, file);
     return value || ".";
 }
-//# sourceMappingURL=package-lifecycle.js.map

package/dist/cli/plan-blocks.d.ts

@@ -16,4 +16,3 @@ export declare function planActionEndpoint(appUrl: string, action: string): stri
 export declare function normalizePlanBlockFormat(value: string | undefined): PlanBlockFormat;
 export declare function defaultPlanBlocksOut(format: PlanBlockFormat): string;
 export declare function fetchPlanBlockCatalog(input: FetchPlanBlockCatalogInput): Promise<FetchPlanBlockCatalogResult>;
-//# sourceMappingURL=plan-blocks.d.ts.map

package/dist/cli/plan-blocks.js

@@ -93,4 +93,3 @@ export async function fetchPlanBlockCatalog(input) {
     }
     throw new Error(lastError || "get-plan-blocks failed.");
 }
-//# sourceMappingURL=plan-blocks.js.map

package/dist/cli/plan-local.d.ts

@@ -244,4 +244,3 @@ export declare function publishVisualAnswerSource(input: PublishVisualAnswerInpu
 }>;
 export declare function runPlan(argv: string[]): Promise<void>;
 export {};
-//# sourceMappingURL=plan-local.d.ts.map

package/dist/cli/plan-local.js

@@ -2378,4 +2378,3 @@ export async function runPlan(argv) {
             process.exit(1);
     }
 }
-//# sourceMappingURL=plan-local.js.map

package/dist/cli/plan-publish-store.d.ts

@@ -59,4 +59,3 @@ export declare function readPlanPublishAuth(filePath?: string): {
     url: string;
     token: string;
 } | null;
-//# sourceMappingURL=plan-publish-store.d.ts.map

package/dist/cli/plan-publish-store.js

@@ -125,4 +125,3 @@ export function readPlanPublishAuth(filePath = planPublishConfigPath()) {
         return null;
     }
 }
-//# sourceMappingURL=plan-publish-store.js.map

package/dist/cli/pr-visual-recap-workflow.d.ts

@@ -1,3 +1,2 @@
 /** Compatibility re-export for the workflow bundled by the recap CLI package. */
 export { PR_VISUAL_RECAP_WORKFLOW_YML } from "@agent-native/recap-cli";
-//# sourceMappingURL=pr-visual-recap-workflow.d.ts.map

package/dist/cli/pr-visual-recap-workflow.js

@@ -1,3 +1,2 @@
 /** Compatibility re-export for the workflow bundled by the recap CLI package. */
 export { PR_VISUAL_RECAP_WORKFLOW_YML } from "@agent-native/recap-cli";
-//# sourceMappingURL=pr-visual-recap-workflow.js.map

package/dist/cli/recap.d.ts

@@ -3,4 +3,3 @@
  * dependency-light package so CI does not install the full framework graph.
  */
 export * from "@agent-native/recap-cli";
-//# sourceMappingURL=recap.d.ts.map

package/dist/cli/recap.js

@@ -3,4 +3,3 @@
  * dependency-light package so CI does not install the full framework graph.
  */
 export * from "@agent-native/recap-cli";
-//# sourceMappingURL=recap.js.map

package/dist/cli/setup-agents.d.ts

@@ -8,4 +8,3 @@ export declare function setupAgentSymlinks(targetDir: string): void;
  * Runs in the current working directory.
  */
 export declare function runSetupAgents(): void;
-//# sourceMappingURL=setup-agents.d.ts.map

package/dist/cli/setup-agents.js

@@ -118,4 +118,3 @@ export function runSetupAgents() {
     setupAgentSymlinks(dir);
     console.log("Agent tool symlinks configured.");
 }
-//# sourceMappingURL=setup-agents.js.map

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

@@ -1,2 +1 @@
 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/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.js

@@ -81,4 +81,3 @@ of using a generic image generator.
 - 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/canvas.d.ts

@@ -1,4 +1,3 @@
 export declare const CANVAS_SURFACE_CORE = "<!-- SHARED-CORE:canvas-surface START -->\n\n**The coordinate rule.** The `surface` sets each artboard's default footprint\nand width \u2014 never set width or use coordinates inside the wireframe HTML.\nBoard-level artboard `x`/`y` IS allowed when it creates clear lanes. A\nlarger explicit artboard `height` is allowed when the screen's content needs\nmore vertical room; canvas frames do not scroll, so reserve enough height to\nshow the entire UI. 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**Full-content artboards.** Canvas frames are pan/zoom surfaces, not scroll\ncontainers. Keep wireframe HTML in natural document flow without an inner\nscroll region or fixed child height. If the screen is taller than the default\nsurface preset, set the artboard's `height` to the measured content height plus\nbreathing room; keep the surface width unchanged. Before handoff, inspect the\nbottom edge of every artboard at default zoom and confirm no control, row, or\nfooter is clipped.\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` sets each artboard's default footprint\nand width \u2014 never set width or use coordinates inside the wireframe HTML.\nBoard-level artboard `x`/`y` IS allowed when it creates clear lanes. A\nlarger explicit artboard `height` is allowed when the screen's content needs\nmore vertical room; canvas frames do not scroll, so reserve enough height to\nshow the entire UI. 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**Full-content artboards.** Canvas frames are pan/zoom surfaces, not scroll\ncontainers. Keep wireframe HTML in natural document flow without an inner\nscroll region or fixed child height. If the screen is taller than the default\nsurface preset, set the artboard's `height` to the measured content height plus\nbreathing room; keep the surface width unchanged. Before handoff, inspect the\nbottom edge of every artboard at default zoom and confirm no control, row, or\nfooter is clipped.\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`\nsets each artboard's default footprint and width, while an explicit taller\n`height` keeps long non-scrolling screens fully visible; 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.js

@@ -160,4 +160,3 @@ 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.`;
-//# sourceMappingURL=canvas.js.map

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

@@ -1,2 +1 @@
 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.js

@@ -50,4 +50,3 @@ inline content is a defect, not a degraded mode.
 
 <!-- SHARED-CORE:connection END -->
 `;
-//# sourceMappingURL=connection.js.map

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

@@ -1,2 +1 @@
 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 database-backed\n  local-folder sources. Prefer Content actions over raw filesystem writes when\n  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-folder synchronization.\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`,\n  `sync-manifest-local-folder-source`, `sync-local-folder-source`,\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- Local folders declared in `agent-native.json` are sources for ordinary\n  SQL-backed Content pages. Use the trusted bridge's pull/check/push workflows to\n  synchronize them; normal document actions always operate on the database.\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\":\"document-id\"}'\npnpm action edit-document '{\"id\":\"document-id\",\"find\":\"old copy\",\"replace\":\"new copy\"}'\npnpm action update-document '{\"id\":\"document-id\",\"content\":\"# Updated\\n\\nBody\"}'\n```\n\nRun `refresh-list` after create/update/delete operations when you need the\nopen Content UI sidebar to repaint immediately.\n\n## Local Folder Sources\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\ndatabase-backed local-folder sources for `docs/`, `blog/`, `content/`, and\n`resources/`, plus a `components/` folder for local MDX components. A trusted\nlocal bridge imports these files into the workspace's canonical Files database.\nRun `sync-manifest-local-folder-source` with a root's generated\n`source.connectionId`, or launch `agent-native content local-files <target>`,\nto connect and pull it. A typical root looks like:\n\n```json\n{\n  \"version\": 1,\n  \"apps\": {\n    \"content\": {\n      \"roots\": [\n        {\n          \"name\": \"Docs\",\n          \"path\": \"docs\",\n          \"kind\": \"docs\",\n          \"extensions\": [\".md\", \".mdx\"],\n          \"source\": {\n            \"type\": \"local-folder\",\n            \"connectionId\": \"local-folder:<opaque-id>\",\n            \"truthPolicy\": \"source_primary\"\n          }\n        }\n      ],\n      \"components\": \"components\",\n      \"extensions\": \"extensions\",\n      \"hide\": [\"**/_*.md\", \"**/_*.mdx\"]\n    }\n  }\n}\n```\n\nLocal-folder synchronization does not make the host language model local, and\nthe hosted Content app cannot read private repo files by itself. File access\nrequires a local Content app, Agent Native Desktop, or another trusted 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- A database page and its source file can change independently. Use folder\n  check/pull/push and resolve reported conflicts rather than silently overwriting\n  either revision.\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.js

@@ -118,4 +118,3 @@ requires a local Content app, Agent Native Desktop, or another trusted bridge.
 - 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/design-exploration-skill.d.ts

@@ -1,2 +1 @@
 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/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.js

@@ -116,4 +116,3 @@ separate those jobs; use it, and hold this bar:
 - If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
   and token values. Never paste bearer tokens into chat or logs.
 `;
-//# sourceMappingURL=design-exploration-skill.js.map

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

@@ -1,2 +1 @@
 export declare const DESIGN_VISUAL_EDIT_SKILL_MD = "---\nname: visual-edit\ndescription: >-\n  Open a running local app in Design overview mode as URL-backed iframe screens\n  for visual editing, flow review, duplication, and route-state exploration.\n  Use when the user asks to inspect, compare, or edit a real local app visually\n  in Design.\nmetadata:\n  visibility: exported\n---\n\n# Visual Edit\n\nUse `/visual-edit` when the user wants to inspect or edit a real local app\nvisually instead of generating standalone Alpine HTML. The source of truth is\nthe running localhost app plus its route URLs. Design shows those routes as\niframe-backed screens on the infinite canvas.\n\n## Installing this skill for an external MCP host\n\nThe hosted install path\n(`npx @agent-native/core@latest skills add visual-edit`, or `design` for the\nfull Design bundle) installs the exported instructions and registers the\nhosted Design MCP connector together. The open Skills CLI path\n(`npx skills@latest add BuilderIO/agent-native --skill visual-edit`) installs\nexported instructions only, with no MCP connector registration.\n\n## Put Design Beside The Chat\n\nPrefer the interactive MCP App returned by `open-visual-edit` when the coding\nhost renders it. The user gets the Design canvas beside the conversation, and\n**Apply design updates** can submit the bounded source-edit handoff back to the\ncurrent host conversation through the standard MCP Apps message bridge. The\nhost may ask the user to confirm the current conversation or choose a new one.\n\nOtherwise, `openUrl` is a credential-free, read-only fallback that is safe to\nshow in model text or retain in logs. Do not claim that fallback is editable:\nthe edit capability is intentionally available only to the host-managed MCP App\nlauncher, where it is hidden from the model and redeemed once.\n\n- In Codex Desktop, prefer the rendered MCP App. Use the in-app Browser for the\n  credential-free `openUrl` only when a read-only fallback is acceptable.\n- In Claude Code Desktop's Code tab, prefer the rendered MCP App. Preview\n  `openUrl` in the Browser pane only as the read-only fallback.\n- In VS Code, use the Agent Native Design webview/deep link described below.\n- Inline browser availability is host-dependent. CLI, remote, or restricted\n  sessions may not expose one. If the inline surface is unavailable or disabled,\n  return the normal **Open design** link instead of claiming it opened.\n\nPrefer the MCP App surface for a connected Design plugin, then the host's\nbrowser/preview tool as the universal fallback. Keep the canvas beside chat\nwhen the host supports rearrangeable panes.\n\nInside Design, use **Show/Hide UI** from the `Cmd+K` menu or press Figma's\n`Shift+\\` shortcut to toggle all editing chrome so only the canvas remains.\nThe same action is available from Design's empty-canvas context menu.\n\n## Core Model\n\n- Each screen is a URL-backed iframe, not copied HTML.\n- Each screen keeps URL metadata: `connectionId`, `routeId`, `path`,\n  `url`, `bridgeUrl`, title, and viewport size.\n- Localhost Edit mode renders the running app through the local bridge as a live\n  iframe with the same editor bridge used by HTML designs. It is never a frozen\n  static DOM snapshot. Editing is direct DOM manipulation against that live\n  document; the parallel `/snapshot` fetch feeds the editable source model only\n  and must never be rendered in the frame.\n- **The `/visual-edit` skill needs no Design account sign-in.**\n  `open-visual-edit` mints a five-minute, single-use capability for the exact\n  `/visual-edit/:designId` local-editor route. The MCP host redeems it outside\n  model-visible text, then opens the existing editor with localhost edit access.\n  This capability is not an account session: `/_agent-native/session` remains\n  signed out, and account-backed save/share/generate actions remain denied.\n- The skill enters through local `pnpm action open-visual-edit`. When that CLI\n  has no account session, the action uses a stable, workspace-scoped local\n  principal to register the bridge, create/reuse the local design, and place\n  screens. That principal exists only inside the in-process CLI call; it is not\n  a browser login and cannot be selected by an HTTP, MCP, or tunneled caller.\n- Public links are always read-only, including on loopback. Loopback peer\n  identity is not an authentication boundary because a tunnel or reverse proxy\n  can make a remote request appear local. A bare `/visual-edit/:designId` or\n  `/design/:designId` URL carries no capability and must never release the\n  connection's `previewToken`.\n- The live editor is same-origin through the local bridge proxy. This boots\n  CSR apps and root-relative assets, but it is still a localhost editing proxy:\n  app-origin cookies, WebSockets/HMR, SSE, and non-GET app API calls may need a\n  future dev-server/plugin integration for perfect parity with the app's own\n  origin.\n- **There are exactly two views.** The infinite canvas is where all editing\n  happens, and the responsive interactive view (Interact) is where the app runs\n  for real. There is no third \"full view\"/focused-edit state \u2014 clicking a screen\n  in the Screens list, or the view toggle, opens the responsive view, and\n  closing it returns to the canvas.\n- Interact keeps the left and right rails and adds a device bar above the canvas\n  (device preset, editable width/height, zoom, close). It renders the app's\n  normal URL so navigation, scrolling, links, and form controls behave as they\n  would in the browser, and the wheel scrolls the app rather than panning the\n  canvas. The canvas view is the opposite: the wheel pans and zooms it, and\n  native interaction inside the frame is suppressed.\n- While a localhost screen has pending live visual edits, do not switch back to\n  Interact until the user either applies the edits to source or explicitly\n  aborts/discards the preview.\n- Alt-drag duplicates a screen. For localhost screens, duplication copies the\n  iframe frame and URL metadata; change the copy's path/query for a new state.\n- Flow visualization is multiple URL states: `/checkout?step=shipping`,\n  `/checkout?step=payment`, `/checkout?step=done`, etc.\n- When the user gives a named flow or numbered screen list, preserve that order\n  and create one screen per URL/path. Shorthand like\n  `localhost:1234/onboarding/1` means\n  `http://localhost:1234/onboarding/1`.\n\n## Useful Canvas Sets\n\nTranslate the user's requested review into the smallest useful set of frames:\n\n- **Multi-step flow:** one ordered frame per route or query state, such as cart,\n  shipping, payment, and confirmation.\n- **Multiple pages:** one frame per meaningful route, such as home, pricing,\n  docs, and account settings.\n- **Responsive comparison:** repeat the same route at the requested desktop,\n  tablet, and mobile viewports so they align in one row.\n- **State review:** repeat a route for meaningful URL-addressable states such as\n  empty, loading, error, modal-open, or selected-item views.\n\nDo not expand every discovered route or every viewport unless the user asks for\nan exhaustive audit. Preserve the user's labels and sequence so the canvas reads\nlike the workflow they described.\n\n## Select And Reprompt\n\nWhen a chat message begins with `[Reprompt selection]`, the selected subtree is\na hard write boundary. The only mutation path is `propose-node-rewrite` with\nthe exact `repromptId`, target, and `baseVersionHash` captured in\n`design-reprompt-pending:<designId>:<fileId>`. Never use `apply-visual-edit`,\n`apply-source-edit`, `write-source`, `write-local-file`, `edit-design`, or any\nother content-writing action for that request. Clarifying questions are allowed,\nbut a requested change must remain a proposal.\n\nProduce one variant by default. Produce two or three only when the instruction\nasks for options. A retry includes `priorProposalId`; keep the same target and\nbase version, incorporate the feedback, and call `propose-node-rewrite` again.\nThe UI previews the returned subtree without persisting it.\n\nUse `resolve-node-rewrite` for the accept/reject lifecycle. Accept applies the\nchosen variant as one version-checked inline/Yjs content transaction so one\nundo restores the prior structure; reject clears the proposal without changing\ncontent. For conversational resolution such as \"apply the second one,\" call\n`view-screen`, read the active `design.reprompt.proposal`, and pass its\n`proposalId` plus the zero-based `variantIndex` to `resolve-node-rewrite`.\n\n## Review Quality\n\n- Treat the running app as the truth. Preserve its component language, tokens,\n  route state, and real content unless the user explicitly asks for a new visual\n  direction.\n- Use multiple URL states to reveal meaningful UX moments: empty/loading/error\n  states, focused panels, modals, responsive breakpoints, and completed flow\n  steps when those matter to the review.\n- For visual edits, compare before/after at the relevant viewport sizes and\n  check key hover/focus/scroll states when the app exposes them.\n\n## Account And Sharing Model\n\n- `/visual-edit/:id` is the dedicated local-editor surface. The one-time\n  handoff returned by `open-visual-edit` opens it with edit access without a\n  Design login. A copied or bare `/visual-edit/:id` URL is read-only because it\n  does not carry the capability.\n- The capability permits live iframe inspection and session-local edits,\n  undo/redo, **Apply design updates** through the connected host/local agent,\n  and **Copy prompt**. Those flows hand bounded source instructions back to the\n  coding agent; they do not silently persist account-owned Design data.\n- Public `/design/:id` links stay read-only without a signed-in owner/editor\n  session. Never use the local capability to upgrade that ordinary sharing\n  surface.\n- Prefer links returned by Design actions or `/_agent-native/open` deep links.\n  Do not surface URLs with `_session=` tokens or hand-build capability URLs.\n- Do not attempt account-backed write actions with the browser capability. The\n  trusted local `open-visual-edit` CLI call may register its bridge, create or\n  reuse its workspace-owned local design, and place screens without an account.\n  Direct source-file action writes, generation, saving into an account, and\n  sharing still require an authenticated action caller. If a signed-out visitor\n  wants those durable account operations, send them through the framework\n  sign-in return flow first.\n\n## Required Local Bridge\n\nThe live-edit bridge is unlocked by a shared secret (the \"bridge token\") that\nmust match on two sides: the local bridge process, and the user's connection row\nin Design (which the browser reads to authorize `/live-edit-bridge`,\n`/read-file`, `/write-file`). Get them to match by letting the\n`open-visual-edit` action mint the token, then starting the\nbridge with it. This is the only ordering that works for the remote-MCP flow \u2014\nthe bridge cannot push its own token to the server without a CLI auth token, so\nthe server mints instead and the bridge adopts.\n\nFrom the target app repo, make sure its dev server is running, then:\n\n**1. Discover routes without starting a durable bridge** (one-shot, exits):\n\n```bash\nnpx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json\n```\n\nThis prints the manifest (routes + capabilities). Parse it to build\n`routeManifest` for the next step. (Skip this if the user already gave explicit\npaths/URLs to place.)\n\nInside the agent-native monorepo itself, use the workspace CLI instead of\n`npx` \u2014 `npx` installs the last published `@agent-native/core`, which will not\ncontain local changes and costs a slow install on every call:\n\n```bash\npnpm dev:cli design connect --url http://localhost:5173 --root templates/<app> --json\n```\n\n**2. Call `open-visual-edit`** (see Action Flow below) with NO `bridgeToken`.\nThe server mints one, stores it on the user's connection row, copies it into the\nplaced screens' metadata, and returns it to you as `bridgeToken`. Capture it.\n\n**3. Start the persistent bridge adopting that token** (single line; prefer the\nenv var so the secret does not appear in `ps`):\n\n```bash\nAGENT_NATIVE_BRIDGE_TOKEN=\"<bridgeToken from step 2>\" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon\n```\n\n(Equivalently, pass `--bridge-token <token>`.) This starts a detached bridge on\n`http://127.0.0.1:7331`, adopts the server-minted token \u2014 so bridge and row\nagree and live-edit authorizes with no self-registration \u2014 and stays alive after\nthe command exits.\n\nFor a manual health/manifest check on the running bridge:\n\n```bash\ncurl http://127.0.0.1:7331/health\n```\n\n`/health` needs no token. The full manifest at `/manifest.json` is\npreview-token protected, so an unauthenticated `curl` of it returns\n`{\"ok\":false,\"error\":\"invalid or missing preview token\"}` \u2014 that response means\nthe bridge is up, not that it is broken.\n\nOnly use `--json` for the step-1 route probe. Never use `--json`, `--once`,\nor `--dry-run` for the durable step-3 bridge: they print the manifest and exit,\nso Design falls back to a non-editable live iframe.\n\nThe bridge listens on a single fixed port (7331) and refuses to start for a\nsecond, different app. It is detached with no log file, so if `--daemon` reports\na timeout, check for a stale process (`lsof -ti:7331`) before retrying.\n\n## Action Flow\n\nPrefer the single `open-visual-edit` action. It registers or\nrefreshes the localhost bridge connection, mints and stores the bridge token,\ncreates or reuses a Design project, places URL-backed screens, stores the active\nvisual-edit context, and navigates to overview mode in one call. This avoids\ncreating a private design under a synthetic CLI user and then handing the browser\na tokenized URL that may be shadowed by an existing session.\n\nCall it BEFORE starting the durable bridge (step 3 above): it does not contact\nthe bridge, so the bridge need not be running yet, and you need its returned\n`bridgeToken` to start the bridge with a matching secret. Omit `bridgeToken`\non the call so the server mints one.\n\n```bash\npnpm action open-visual-edit '{\n  \"title\": \"Docs homepage visual edit\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"bridgeUrl\": \"http://127.0.0.1:7331\",\n  \"rootPath\": \"/absolute/path/to/app\",\n  \"routeManifest\": { \"...\": \"from /manifest.json\" },\n  \"paths\": [\"/\", \"/pricing\", \"/checkout?step=payment\"]\n}'\n```\n\nThe action returns `designId`, `connectionId`, `bridgeToken`, `screens`,\n`urlPath`, and a credential-free `openUrl`. Its MCP App metadata separately\ncarries the one-time editor launcher so the host can redeem it without showing\nthe capability to the model or retaining it in the action link. Keep\n`designId`/`connectionId` in the chat context for follow-ups, and pass\n`bridgeToken` to `design connect` (step 3) to start the bridge. On follow-up\ncalls reusing an existing `connectionId`, the same token is returned (it is\nminted once and reused), so the running bridge stays valid.\n\n### Desktop and mobile side by side\n\nPass `viewports` to place every requested route once per viewport. Frames lay\nout as a grid: one row per route, one column per viewport. Presets are\n`desktop` (1280x900), `laptop` (1440x900), `tablet` (834x1112), and `mobile`\n(390x844); an explicit `{ \"label\": \"...\", \"width\": N, \"height\": N }` also works.\n\n```bash\npnpm action open-visual-edit '{\n  \"title\": \"Tasks responsive visual edit\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"bridgeUrl\": \"http://127.0.0.1:7331\",\n  \"rootPath\": \"/absolute/path/to/app\",\n  \"paths\": [\"/tasks\", \"/inbox\"],\n  \"viewports\": [\"desktop\", \"mobile\"]\n}'\n```\n\nPrefer this over two separate calls with `defaultWidth`/`defaultHeight`: it\nkeeps each route's viewports aligned in a row and titles them\n`Tasks \u2014 Desktop` / `Tasks \u2014 Mobile` so the canvas reads clearly. `viewports`\noverrides `defaultWidth`/`defaultHeight`. With no `routes`/`paths`, it expands\nevery route in the localhost manifest, which is usually far more frames than\nthe user wants \u2014 name the paths.\n\n### Adding more page frames later\n\nCall `open-visual-edit` again with the same `designId` and `connectionId` and\nonly the new paths. Existing frames for the same route and viewport are\nrefreshed in place rather than duplicated, and a frame the user has dragged or\nresized keeps its position unless you explicitly pass `x`/`y`/`width`/`height`.\n\n```bash\npnpm action open-visual-edit '{\n  \"designId\": \"<existing-design-id>\",\n  \"connectionId\": \"<existing-connection-id>\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"paths\": [\"/settings\", \"/team\"],\n  \"startY\": 2200\n}'\n```\n\nDo NOT add `defaultWidth`/`defaultHeight` just to restate the default size:\nsupplying either one marks the viewport as explicitly requested, which\noverwrites frame sizes the user has already adjusted on the canvas.\n\nFor a numbered flow the user describes in chat, keep the labels and order:\n\n```bash\npnpm action open-visual-edit '{\n  \"designId\": \"<existing-design-id>\",\n  \"connectionId\": \"<existing-connection-id>\",\n  \"devServerUrl\": \"http://localhost:1234\",\n  \"routes\": [\n    { \"url\": \"localhost:1234/onboarding/1\", \"title\": \"Screen 1\" },\n    { \"url\": \"localhost:1234/onboarding/2\", \"title\": \"Screen 2\" },\n    { \"url\": \"localhost:1234/onboarding/3\", \"title\": \"Screen 3\" }\n  ]\n}'\n```\n\nIf no `routes` or `paths` are supplied, `open-visual-edit` uses every route\nfrom the localhost manifest.\n\nFallback, only when `open-visual-edit` is unavailable:\n\n1. Register or refresh the bridge with `connect-localhost`, passing the\n   `/manifest.json` result as `routeManifest` and `capabilities`.\n2. Create or reuse a Design project with `create-design`.\n3. Place URL-backed screens with `add-localhost-screens`.\n4. Navigate to overview mode with `navigate`.\n\n## Open The Design Surface\n\n- Use the `link`, `deepLink`, or MCP App embed returned by Design actions so\n  the user sees the canvas. Follow **Put Design Beside The Chat**: prefer the\n  MCP App; otherwise surface the credential-free **Open design** link.\n- Return or open the MCP App first. Its host-managed launcher carries the\n  one-time local-editor capability. The credential-free `openUrl` / action link\n  is the safe read-only fallback; never build a capability URL yourself.\n- Never return or open a hand-built `/design/:id?_session=...` URL.\n- If the user is working in VS Code, the Agent Native extension can open the\n  same URL via\n  `vscode://builder.agent-native/open?url=<encoded-design-url>`. Its\n  `Agent Native: Open Design Canvas` command also starts the local bridge and\n  opens hosted Design in the VS Code side panel.\n- After `open-visual-edit`, confirm the Design editor is in overview mode\n  with the requested URL-backed frames visible, and that they render the app\n  rather than a spinner. Do not stop at \"screens added\" when the user asked to\n  inspect or edit visually.\n\n## Applying Visual Edits Back To Source\n\nCanvas edits on a localhost screen do not write source as you make them. They\naccumulate as pending edits and the editor shows an **Apply design updates**\nbutton on the canvas. In an MCP App, clicking it hands the bounded structured\nprompt to the current host coding conversation. In an ordinary browser or\nstandalone Design page, it falls back to the local Design agent. The dropdown's\n**Copy prompt to your agent** action is the universal manual fallback.\n\n- Style, text, and drag/drop structure edits all collect into the same pending\n  batch, so the user can make several changes and apply once.\n- After the write lands, the target app's own dev-server HMR refreshes the\n  frames \u2014 no manual reload. If frames do not refresh, the write did not land;\n  say so rather than assuming.\n- The separate disk-icon \"Apply to source\" button is the deterministic\n  whole-file HTML/CSS writer. It is intentionally disabled for compiled\n  `.jsx`/`.tsx` routes \u2014 those must go through the agent path above.\n\n## Editing URLs\n\nKeep localhost screens as URL files plus `screenMetadata[fileId]`. Do not\nreplace them with copied `srcdoc` HTML unless the user explicitly asks for a\nfrozen snapshot. To change a state, rerun `open-visual-edit` with the new\npath/query or duplicate the screen and update the copy's URL metadata.\n\n## Local Files in the Code Tab\n\nOnce a connection is registered, the design editor's Code panel (left rail \u2192\nCode, or `navigate --view editor --designId <id> --leftPanel code`) shows a\nlocal-files workspace root for that connection next to the design's own files.\nTreat that root like VS Code opened at the connected project directory: file\ntree, search, open/edit, and save are backed by the real local files. It lists\nthe connected app's text/code files through the bridge\n(`list-local-files` / `read-local-file`); build output, `node_modules`,\n`.git`, and secret-looking paths (`.env*`, key files) are always excluded.\n\n- Browsing and reading need only editor access on the design plus the running\n  bridge.\n- Saving goes through `write-local-file`: the first save opens the\n  write-consent dialog (an 8-hour, folder-scoped grant) and retries\n  automatically once granted. Only text/code files are writable; secret paths\n  are always blocked.\n- If the agent calls `write-local-file` directly (not through a UI save) and it\n  fails with \"no write-consent grant\", call `request-localhost-write-consent`.\n  It opens the write-consent dialog in the editor, or reports `alreadyGranted`\n  if one already exists. Granting is human-only \u2014\n  `grant-localhost-write-consent` is hidden from agents, so you cannot approve\n  it yourself. Tell the user to click \"Allow writes\", then retry\n  `write-local-file` once. Do not keep retrying blindly: the write stays\n  blocked until the user approves.\n- Saves are conflict-checked against the file's on-disk version \u2014 a file that\n  changed since it was read fails with a version conflict instead of being\n  overwritten.\n\n## React Source Writeback\n\n- Use compiler/debug provenance (project-relative file, line, column,\n  component, and runtime multiplicity) to locate React/TSX source. Treat it as\n  evidence, not as permission for a generic AST structural transform.\n- Read `positionPrecision` on every anchor before you trust `line`/`column`.\n  `authored` means those are the real JSX coordinates. `transformed` means they\n  are the dev server's own output coordinates \u2014 React 19 removed `_debugSource`\n  and exposes only an owner stack, so this is the normal case on a Vite/Next\n  dev server, and the line will not match the file. `unknown` means no tier was\n  reported. On anything but `authored`, use the file and component to find the\n  element by its JSX shape and re-derive the line from the file you read; never\n  edit at the reported line.\n- A single-instance leaf text edit, literal `className`/`class` edit, or flat\n  literal `style={{ ... }}` property may use `apply-visual-edit` with a\n  `local-file` source and a complete `target.sourceAnchor`. Forward the\n  anchor's `positionPrecision` with it \u2014 the action refuses a `transformed`\n  anchor with `status: \"needsAgent\"` instead of seeking to a line that means\n  something else in the authored file. Preview first (omit `persist`), inspect\n  `proposedDiff`, then call with `persist: true`.\n- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated\n  `.map()` instances, shared components, breakpoint-scoped edits, and\n  cross-file changes go through the coding agent with complete subject/target\n  anchors and their runtime relationship. `apply-visual-edit` refuses these\n  with `status: \"needsAgent\"` rather than guessing.\n- Before each write, read the file and pass its exact `versionHash` to\n  `write-local-file` with `requireExpectedVersionHash: true`; on conflict,\n  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms\n  the result. Human write consent remains mandatory and agents cannot grant it.\n\n## Verification\n\n- `list-localhost-connections` returns the expected connection and routes.\n- The Design editor opens in overview mode.\n- Every requested screen renders the intended localhost URL, showing real app\n  content rather than an endless loading spinner.\n- The screen iframe carries a `src`, not a `srcdoc`. A localhost screen with a\n  `srcdoc` is a bug, not a slow load \u2014 check it in the browser devtools before\n  reporting the canvas as working.\n- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.\n- A query/path edit changes only the target screen's URL metadata and iframe.\n- The Code tab shows a local-files root for the connection and opens its files.\n";
-//# sourceMappingURL=design-visual-edit-skill.d.ts.map

package/dist/cli/skills-content/design-visual-edit-skill.js

@@ -470,4 +470,3 @@ the connected app's text/code files through the bridge
 - A query/path edit changes only the target screen's URL metadata and iframe.
 - The Code tab shows a local-files root for the connection and opens its files.
 `;
-//# sourceMappingURL=design-visual-edit-skill.js.map

package/dist/cli/skills-content/document-quality.d.ts

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

package/dist/cli/skills-content/document-quality.js

@@ -192,4 +192,3 @@ questions in a single bottom \`question-form\` and a pre-handoff visual check.
 Before authoring the plan document, READ \`references/document-quality.md\` in this
 skill directory — it is the single source of truth for the document quality bar.
 Do not write the document from memory.`;
-//# sourceMappingURL=document-quality.js.map

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

@@ -1,4 +1,3 @@
 export declare const EXEMPLAR_CORE = "<!-- SHARED-CORE:exemplar START -->\n\n**GOOD.** A UI-first plan for a todo app: a canvas with a `desktop` artboard whose\n`data.html` is a real flex layout \u2014 a sidebar of links (`Inbox 12`, `Today 4`,\n`Done`), a main column with an `<h1>Today</h1>`, accent `.wf-pill`s for the\nfilters, a muted section label `OVERDUE`, and `.wf-card` task rows carrying real\ntitles, due dates, and a primary `button.primary` \u2014 styled only through bare\nelements, helper classes, and `--wf-*` tokens, so the renderer applies the\ncorrect desktop footprint, theme, and one subtle whole-frame wobble. Plain-text\ndesigner notes sit spaced off the frame, pointing only at the controls that need\nexplanation. Below it, a Claude/Codex-grade document: objective and\ndone-criteria, a few `code` blocks (grouped in a vertical `tabs` block when\nmore than one) showing the real shape of the load-bearing files, a `callout`\nwith `tone=\"decision\"` stating the chosen approach with a `columns` block\nweighing the two real options behind it,\nand a validation step \u2014 none of it repeating the canvas. If the task also\nchanges a multi-step completion flow, the same top area includes a Prototype tab\nwhose screens use the same labels and states as the canvas artboards, with\n`data-goto` controls for the sequence. This is the bar.\n\n**GOOD.** A broad product-architecture plan opens with a plain recommendation\nand one concrete app state before the abstraction. The first canvas artboard is\npure product UI that matches the current app shell; nearby notes explain the\nuser-visible delta. A separate diagram below shows the mechanics, such as file\nor data flow. The document then separates the reusable core from app/provider\nadapters and examples, covers contracts, folder or schema shape, sync\nboundaries, roadmap, non-goals, a bottom Open Questions form for unresolved\ndecisions, and a verification section with at least one realistic end-to-end\nsmoke. A reviewer who was not in the chat gets the idea from the top snapshot\nbefore reading the technical plan.\n\n**GOOD.** A `/visual-plan` for a backend architecture review: no top canvas.\nThe document opens with context and a legend, then repeats recommendation cards:\ntitle, confidence/category badges, a monospace grid of real file paths, one\ninline two-dimensional before/after or layered architecture diagram, and terse\nProblem/Solution/Why bullets using the codebase's vocabulary. The diagram uses\nspace to show boundaries, layers, and ownership; it is not a default\nleft-to-right chain. The plan ends with a top recommendation and a bottom\nquestion-form only if the next architecture direction is genuinely open. This is\nbetter than a top canvas because each diagram is local to the claim it supports.\n\n**BAD.** A `data.html` with hard-coded hex colors, a `font-family`, or fixed\npixel width/height; gray placeholder bars \"insinuating\" text on a non-skeleton\nframe; a forced desktop + mobile pair for a popover; floating bordered\nannotation cards hugging the frames; a fresh hand-authored kit-tree `screen`\ninstead of `html`; a multi-step UI flow with only static frames and no prototype\ntab; a mockup escaped into a document `custom-html` block; and a marketing-style\ndocument with a hero heading and value props that just restates what the canvas\nalready shows. Also bad: an architecture-only plan forced into a top canvas of\nlabeled boxes with overlapping text, where the actual code evidence and\nrecommendations live elsewhere; a product wireframe that mixes a real screen\nwith repo names, file-contract arrows, architecture explanations, or a made-up\npermanent inspector; and a plan that describes itself as a revision of a prior\nconversation instead of a standalone proposal. Never produce this.\n\n<!-- SHARED-CORE:exemplar END -->";
 export declare const EXEMPLAR_REFERENCE_MD = "# Good vs. bad exemplar \u2014 single source of truth\n\nThis file is the canonical worked example of a great plan (and the anti-patterns\nto avoid). Read it alongside the document-quality and canvas references before\nauthoring a plan; it is the bar these plans must clear.\n\n<!-- SHARED-CORE:exemplar START -->\n\n**GOOD.** A UI-first plan for a todo app: a canvas with a `desktop` artboard whose\n`data.html` is a real flex layout \u2014 a sidebar of links (`Inbox 12`, `Today 4`,\n`Done`), a main column with an `<h1>Today</h1>`, accent `.wf-pill`s for the\nfilters, a muted section label `OVERDUE`, and `.wf-card` task rows carrying real\ntitles, due dates, and a primary `button.primary` \u2014 styled only through bare\nelements, helper classes, and `--wf-*` tokens, so the renderer applies the\ncorrect desktop footprint, theme, and one subtle whole-frame wobble. Plain-text\ndesigner notes sit spaced off the frame, pointing only at the controls that need\nexplanation. Below it, a Claude/Codex-grade document: objective and\ndone-criteria, a few `code` blocks (grouped in a vertical `tabs` block when\nmore than one) showing the real shape of the load-bearing files, a `callout`\nwith `tone=\"decision\"` stating the chosen approach with a `columns` block\nweighing the two real options behind it,\nand a validation step \u2014 none of it repeating the canvas. If the task also\nchanges a multi-step completion flow, the same top area includes a Prototype tab\nwhose screens use the same labels and states as the canvas artboards, with\n`data-goto` controls for the sequence. This is the bar.\n\n**GOOD.** A broad product-architecture plan opens with a plain recommendation\nand one concrete app state before the abstraction. The first canvas artboard is\npure product UI that matches the current app shell; nearby notes explain the\nuser-visible delta. A separate diagram below shows the mechanics, such as file\nor data flow. The document then separates the reusable core from app/provider\nadapters and examples, covers contracts, folder or schema shape, sync\nboundaries, roadmap, non-goals, a bottom Open Questions form for unresolved\ndecisions, and a verification section with at least one realistic end-to-end\nsmoke. A reviewer who was not in the chat gets the idea from the top snapshot\nbefore reading the technical plan.\n\n**GOOD.** A `/visual-plan` for a backend architecture review: no top canvas.\nThe document opens with context and a legend, then repeats recommendation cards:\ntitle, confidence/category badges, a monospace grid of real file paths, one\ninline two-dimensional before/after or layered architecture diagram, and terse\nProblem/Solution/Why bullets using the codebase's vocabulary. The diagram uses\nspace to show boundaries, layers, and ownership; it is not a default\nleft-to-right chain. The plan ends with a top recommendation and a bottom\nquestion-form only if the next architecture direction is genuinely open. This is\nbetter than a top canvas because each diagram is local to the claim it supports.\n\n**BAD.** A `data.html` with hard-coded hex colors, a `font-family`, or fixed\npixel width/height; gray placeholder bars \"insinuating\" text on a non-skeleton\nframe; a forced desktop + mobile pair for a popover; floating bordered\nannotation cards hugging the frames; a fresh hand-authored kit-tree `screen`\ninstead of `html`; a multi-step UI flow with only static frames and no prototype\ntab; a mockup escaped into a document `custom-html` block; and a marketing-style\ndocument with a hero heading and value props that just restates what the canvas\nalready shows. Also bad: an architecture-only plan forced into a top canvas of\nlabeled boxes with overlapping text, where the actual code evidence and\nrecommendations live elsewhere; a product wireframe that mixes a real screen\nwith repo names, file-contract arrows, architecture explanations, or a made-up\npermanent inspector; and a plan that describes itself as a revision of a prior\nconversation instead of a standalone proposal. Never produce this.\n\n<!-- SHARED-CORE:exemplar END -->\n";
 export declare const EXEMPLAR_REFERENCE_POINTER = "For a worked example of the bar \u2014 a great UI-first plan and `/visual-plan`, plus\nthe anti-patterns to avoid \u2014 READ `references/exemplar.md` in this skill\ndirectory before authoring a plan.";
-//# sourceMappingURL=exemplar.d.ts.map

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

@@ -65,4 +65,3 @@ ${EXEMPLAR_CORE}
 export const EXEMPLAR_REFERENCE_POINTER = `For a worked example of the bar — a great UI-first plan and \`/visual-plan\`, plus
 the anti-patterns to avoid — READ \`references/exemplar.md\` in this skill
 directory before authoring a plan.`;
-//# sourceMappingURL=exemplar.js.map

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

@@ -1,2 +1 @@
 export declare const HELP = "npx @agent-native/core@latest skills\n\nUsage:\n  npx @agent-native/core@latest skills list\n  npx @agent-native/core@latest skills status [assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]\n  npx @agent-native/core@latest skills update [assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]\n  npx @agent-native/core@latest skills add assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]\n  npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]\n\nExamples:\n  npx @agent-native/core@latest skills add assets\n  npx @agent-native/core@latest skills add rewind --client codex --scope user --yes\n  npx @agent-native/core@latest skills add content --mode local-files\n  npx @agent-native/core@latest skills add design-exploration\n  npx @agent-native/core@latest skills add visual-edit\n  npx @agent-native/core@latest skills add visual-plan\n  npx @agent-native/core@latest skills add visual-recap\n  npx @agent-native/core@latest skills add visualize-repo\n  npx @agent-native/core@latest skills add visual-recap --with-github-action\n  npx @agent-native/core@latest skills add visual-plan --mode local-files\n  npx @agent-native/core@latest skills add visual-plan --mode self-hosted --mcp-url https://my-plan-app.example.com\n  npx @agent-native/core@latest skills status visual-plan\n  npx @agent-native/core@latest skills update visual-plan\n  npx @agent-native/core@latest skills update scaffold --project\n  npx @agent-native/core@latest skills add visual-plan --no-connect\n  npx @agent-native/core@latest skills add context-xray --client all\n  npx @agent-native/core@latest skills add assets --client claude-code\n  npx @agent-native/core@latest skills add assets --mcp-url https://my-app.ngrok-free.dev\n  npx @agent-native/core@latest skills add ./dist/assets-skill --client codex\n  npx @agent-native/core@latest skills add BuilderIO/skills --client codex --scope project\n  npx @agent-native/core@latest skills add BuilderIO/skills --with-github-action\n\nThe add command installs the SKILL.md instructions, registers the app-backed\nMCP connector, and then authenticates it in one step so you do not hit an OAuth\nwall on the first tool call. Hosted installs can configure Claude Code, Codex,\nClaude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files\ninstruction installs target the shared .agents skill path used by Codex, Pi,\nCursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill\npath when selected. Pass --client to narrow it. Authentication reuses\n\"npx @agent-native/core@latest connect\": OAuth-capable clients (Claude Code,\nCursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate\ninside that host, while Codex / Cowork run the browser device-code flow. In a\nnon-interactive shell or CI the auth step is skipped and the exact\n\"npx @agent-native/core@latest connect <url> --client all\" command is printed instead.\n\nRunning \"npx @agent-native/skills@latest add ...\" uses this same shared install\nflow with the broader BuilderIO skills catalog enabled. Pass --no-connect to\nregister MCP where possible without authenticating (leave auth to the host or run\n\"npx @agent-native/core@latest connect\" later). Pass --mcp-url to register that connector against\na custom origin (an ngrok tunnel, a local dev server, or a self-hosted\ndeployment) instead of the built-in hosted default \u2014 a bare origin gets the\nstandard /mcp path appended. Use app-skill pack for marketplace\nbundles and custom adapter output.\n\nWhen installing visual-plan, visual-recap, or visualize-repo interactively, the\nCLI asks where Plans artifacts should live: hosted Plans for shareable\nlinks/comments, local files for \"No sharing, all local.\", or a\nself-hosted/custom Plan app URL.\nPass --mode to choose directly. Local-files mode skips MCP registration and\nauth and installs instructions that default to a no-auth block catalog fetch,\nMDX folders, and the localhost bridge viewer.\n\nWhen installing content with --mode local-files, the CLI installs Content\ninstructions and writes or updates agent-native.json with repo-backed Markdown /\nMDX roots for docs, blog, content, and resources. Use a local Content app, Agent\nNative Desktop, or another trusted local bridge for Content actions to read and\nwrite those files.\n\nWhen installing visual-recap interactively, the CLI offers to add the optional PR\nVisual Recap GitHub Action. Pass --with-github-action to write it directly, then\nrun \"npx @agent-native/core@latest recap setup\" / \"npx @agent-native/core@latest recap doctor\" to configure and\nverify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.\n\nThe status/update commands inspect copied Agent Native skill folders and refresh\ntheir instruction files from the current @agent-native/core package. In generated\napps/workspaces, \"skills update scaffold --project\" refreshes the framework\nskills copied into the scaffold and repairs AGENTS.md / CLAUDE.md and\n.agents/skills / .claude/skills compatibility links.";
-//# sourceMappingURL=help.d.ts.map

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

@@ -76,4 +76,3 @@ their instruction files from the current @agent-native/core package. In generate
 apps/workspaces, "skills update scaffold --project" refreshes the framework
 skills copied into the scaffold and repairs AGENTS.md / CLAUDE.md and
 .agents/skills / .claude/skills compatibility links.`;
-//# sourceMappingURL=help.js.map

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

@@ -21,4 +21,3 @@ export * from "./local-files.js";
 export * from "./visual-plan-skill.js";
 export * from "./visual-recap-skill.js";
 export * from "./visualize-repo-skill.js";
-//# sourceMappingURL=index.d.ts.map

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

@@ -21,4 +21,3 @@ export * from "./local-files.js";
 export * from "./visual-plan-skill.js";
 export * from "./visual-recap-skill.js";
 export * from "./visualize-repo-skill.js";
-//# sourceMappingURL=index.js.map

package/dist/cli/skills-content/local-files.d.ts

@@ -1,2 +1 @@
 export declare const LOCAL_FILES_REFERENCE_MD = "# Local-files privacy mode \u2014 single source of truth\n\nThis file is the canonical contract for fully local, no-database planning and\nrecaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it\nin full before using local-files mode; do not call any hosted Plan tool for a\nlocal plan/recap except the schema-only block-catalog lookup described below.\n\n<!-- SHARED-CORE:local-files START -->\n\n**When to use it.** Use local-files privacy mode when the user explicitly asks\nfor no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local\nfiles, offline/private work, or repo-owned/source-controlled artifacts, or when\n`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo\npolicy says the work must stay under their own brand, domain, source control, or\ninfrastructure. In this mode the plan/recap data must never be sent to the Plan\nMCP server or the Plan app action surface. This is the only exception to the\nalways-publish rule in `references/connection.md`.\n\nThe local-files contract:\n\n- **Read context locally.** Read source, diff, and stat context from local files\n  and shell commands only. For recaps, the\n  `npx @agent-native/core@latest recap collect-diff`, `scan`, and\n  `build-prompt --local-files` helpers are safe \u2014 they operate on local files and\n  do not write to the Plan database.\n- **Fetch the block catalog first** (it sends no plan content). Use the MCP\n  `get-plan-blocks` tool if it is already available, or run\n  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that\n  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.\n  Use `--format schema` when you need exact nested fields. If network access is\n  unavailable, use the bundled `references/*.md` and rely on `plan local check` to\n  catch invalid tags. Copy the catalog examples verbatim for the fields the\n  registry table cannot encode: `checklist` items need `id` and `label`;\n  `question-form` questions need `id`, `title`, and `mode`, and each option needs\n  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive\n  \u2014 encode multiline code as JSON string attributes such as `code={\"const x =\\n  y\"}`\n  (a static template literal is accepted only when it has no `${...}`\n  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the\n  renderer schema), so a green `check` does not guarantee the plan renders.\n  `plan local verify` also stays on-device: it uses the offline lint unless it\n  can reach a Plan renderer on an explicit loopback `--app-url`.\n- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the\n  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`\n  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The\n  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and\n  optional `.plan-state.json`. For a recap, set `kind: \"recap\"` and\n  `localOnly: true` in the frontmatter/state. Use that exact folder as\n  `<plan-dir>` in every command below.\n- **Check, then serve.** Run\n  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any\n  preview, then\n  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`\n  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local\n  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local\n  token file and do not commit it. The URL opens the hosted Plan UI but reads from\n  the localhost bridge on this machine, so it is not shareable across machines.\n  The token is carried in the URL fragment (which is not sent to the hosted\n  origin), and the local-plan route disables DOM autocapture and session replay\n  while retaining sanitized pageviews and error monitoring. On\n  macOS `--open` prefers Chromium browsers; if Safari opens, switch to\n  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the\n  HTTP localhost bridge. If the Plan app itself is running locally with the same\n  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly\n  offline environment, hand off the `<plan-dir>` path after `plan local check` and\n  note that interactive preview requires network access to the hosted Plan UI or a\n  running local Plan app.\n- **Headless verify.** Run\n  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.\n  It starts the bridge and checks the private-network preflight and JSON payload\n  entirely on loopback. It never sends MDX or assets to a remote validation\n  action. When `--app-url` points to a loopback Plan app, verify also validates\n  against that local app's real renderer schema via `validate-local-plan-source`.\n  A non-`ok` result with\n  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.\n  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`\n  is `false`, verify used the offline lint because the app URL was remote or the\n  local Plan app was unavailable. Run a local Plan app and pass\n  `--app-url http://localhost:8096` for the authoritative check. If the browser hangs on\n  \"Loading plan\", fetch the `bridgeUrl` from the verify/serve JSON to read the\n  concrete validation error.\n- **Never call hosted tools for that plan/recap.** Do not call\n  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,\n  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,\n  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,\n  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any\n  other hosted Plan tool \u2014 except the schema-only block-catalog lookup above.\n- **Feedback is file/chat feedback.** Update the MDX files directly, rerun\n  `plan local check`, and rerun `serve` or `verify` when that preview path is\n  available. Summarize the new local URL when one exists; otherwise summarize the\n  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage\n  attachment, and publish/export receipts are unavailable until the user\n  explicitly opts into publishing.\n\nLocal-files mode prevents plan/recap content from being uploaded to the\nAgent-Native Plan server or database. It does not by itself make the coding agent's language model local;\nfor that stronger boundary the host agent/model must also be local or otherwise\napproved by the user.\n\n<!-- SHARED-CORE:local-files END -->\n";
-//# sourceMappingURL=local-files.d.ts.map

package/dist/cli/skills-content/local-files.js

@@ -98,4 +98,3 @@ approved by the user.
 
 <!-- SHARED-CORE:local-files END -->
 `;
-//# sourceMappingURL=local-files.js.map

package/dist/cli/skills-content/plan-setup-auth.d.ts

@@ -6,4 +6,3 @@
  * `.agents/skills/*` are guarded byte-identical by `skills.sync.spec.ts`.
  */
 export declare const PLAN_SETUP_AUTH_MD = "## Setup & Authentication\n\nThere are two ways into Plans.\n\n**Coding agent (CLI).** Install once with the Agent-Native CLI. The command\ninstalls the Plans skills, registers the hosted Plans MCP connector, and runs\nauth/setup for the selected local client(s) in the same step (a one-time browser\nsign-in at setup \u2014 this is intended), so the first tool call in that client does\nnot hit an OAuth wall:\n\n```bash\nnpx @agent-native/core@latest skills add visual-plans\n```\n\nAfter that, `/visual-plan`, `/visual-recap`, and `/visualize-repo` are the\ninstalled slash commands. If you only need one command, use\n`skills add visual-plan`, `skills add visual-recap`, or\n`skills add visualize-repo` instead. The other planning modes\n(`create-ui-plan`, `create-prototype-plan`, `create-plan-design`,\n`create-visual-questions`) are MCP tools reachable from `/visual-plan`, not\nseparate slash commands. Pass `--no-connect` to register the connector without\nauthenticating, then run\n`npx @agent-native/core@latest connect https://plan.agent-native.com --client all`\nwhenever you are ready, or choose a narrower `--client`. Auth and MCP tool\nloading are per client config/session.\n\n**Local-only / text installs.** If the user wants no sharing and all local files,\ninstall with `--mode local-files`:\n\n```bash\nnpx @agent-native/core@latest skills add visual-plans --mode local-files\n```\n\nThis mode does not register the Plan MCP connector. Before authoring structured\nMDX, fetch the no-auth, schema-only block catalog with\n`npx @agent-native/core@latest plan blocks --out plan-blocks.md`, read that file,\nwrite the MDX folder locally, run `plan local check`, then run `plan local serve`.\nFor repo-wide visual docs, run\n`npx @agent-native/core@latest visualize-repo --open` to create/update\n`agent-native.json`, seed `.agent-native/visual-docs/repo-overview`, and open\nthe local bridge.\nPlain text skill\ninstalls (Vercel Skills CLI, copied GitHub files, etc.) can follow that same\nlocal flow if `@agent-native/core` is available. Text alone cannot register\nMCP tools; hosted/shareable Plans still need the Agent-Native CLI\ninstall/reconnect step above.\n\n**Browser (people you share with).** Open the Plans editor and create & edit\nwith no sign-up \u2014 you work as a guest. Sign in only when you want to save or\nshare; signing in claims the plans you made as a guest into your account.\n\nSharing and commenting require an account: public/shared plans are viewable by\nanyone with the link, but commenting on them needs an agent-native account.\n\nFor no-account, no-DB plan storage, use local-files mode and the local bridge\ncommand. The optional `plan blocks` lookup reads only public schema metadata.\nIf network access is unavailable, use the bundled references and a local Plan\napp/runtime for validation.\n\nIf a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`,\ndo not keep retrying the tool. Stop and give the user the reconnect step for the\nclient they are using: Codex/Codex Desktop should run\n`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`\nand start a new Codex session; Claude Code should run `/mcp` and choose\nAuthenticate/Reconnect for the plan connector, or run the reconnect command with\n`--client claude-code` and restart Claude. To refresh every local client config\nthat already has the Plan entry, use `--client all`, then restart/reload each\nclient. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by\nURL regardless of connector name. Never reinstall from scratch just to fix auth.\nContinue once the connector is available.\n\nHosted default: connect `https://plan.agent-native.com/mcp`. Do\nnot put shared secrets in skill files.";
-//# sourceMappingURL=plan-setup-auth.d.ts.map

package/dist/cli/skills-content/plan-setup-auth.js

@@ -78,4 +78,3 @@ Continue once the connector is available.
 
 Hosted default: connect \`https://plan.agent-native.com/mcp\`. Do
 not put shared secrets in skill files.`;
-//# sourceMappingURL=plan-setup-auth.js.map