@agent-native/core 0.97.0 → 0.98.0

package/corpus/core/src/cli/skills-content/canvas.ts

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

package/corpus/core/src/cli/skills-content/connection.ts

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

package/corpus/core/src/cli/skills-content/content-skill.ts

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

package/corpus/core/src/cli/skills-content/design-exploration-skill.ts

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

package/corpus/core/src/cli/skills-content/design-visual-edit-skill.ts

@@ -0,0 +1,228 @@
+export const DESIGN_VISUAL_EDIT_SKILL_MD = `---
+name: visual-edit
+description: >-
+  Open a running local app in Design overview mode as URL-backed iframe screens
+  for visual editing, flow review, duplication, and route-state exploration.
+  Use when the user asks to inspect, compare, or edit a real local app visually
+  in Design.
+metadata:
+  visibility: exported
+---
+
+# Visual Edit
+
+Use \`/visual-edit\` when the user wants to inspect or edit a real local app
+visually instead of generating standalone Alpine HTML. The source of truth is
+the running localhost app plus its route URLs. Design shows those routes as
+iframe-backed screens on the infinite canvas.
+
+## Core Model
+
+- Each screen is a URL-backed iframe, not copied HTML.
+- Each screen keeps URL metadata: \`connectionId\`, \`routeId\`, \`path\`,
+  \`url\`, \`bridgeUrl\`, title, and viewport size.
+- Start in Design's screen overview mode. In overview, screens are static
+  design frames; full-screen focus is for scrolling and app interaction.
+- Alt-drag duplicates a screen. For localhost screens, duplication copies the
+  iframe frame and URL metadata; change the copy's path/query for a new state.
+- Flow visualization is multiple URL states: \`/checkout?step=shipping\`,
+  \`/checkout?step=payment\`, \`/checkout?step=done\`, etc.
+- When the user gives a named flow or numbered screen list, preserve that order
+  and create one screen per URL/path. Shorthand like
+  \`localhost:1234/onboarding/1\` means
+  \`http://localhost:1234/onboarding/1\`.
+
+## Review Quality
+
+- Treat the running app as the truth. Preserve its component language, tokens,
+  route state, and real content unless the user explicitly asks for a new visual
+  direction.
+- Use multiple URL states to reveal meaningful UX moments: empty/loading/error
+  states, focused panels, modals, responsive breakpoints, and completed flow
+  steps when those matter to the review.
+- For visual edits, compare before/after at the relevant viewport sizes and
+  check key hover/focus/scroll states when the app exposes them.
+
+## Account And Sharing Model
+
+- The \`/visual-edit\` entry route can open before the viewer signs in. Public
+  \`/design/:id\` editor links can also render read-only public designs without a
+  session.
+- Prefer links returned by Design actions or \`/_agent-native/open\` deep links.
+  Do not surface URLs with \`_session=\` tokens. Query sessions are only a
+  fallback after normal cookie resolution, so an existing browser session can
+  still open the design as a different user and show "Design not found".
+- Do not attempt anonymous write actions. Bridge registration, design creation,
+  screen placement, generation, saving, and sharing are account-backed. If a
+  signed-out visitor wants to save or share, send them through the framework
+  sign-in return flow, then save or copy the design into that account before
+  opening the share dialog.
+
+## Required Local Bridge
+
+The live-edit bridge is unlocked by a shared secret (the "bridge token") that
+must match on two sides: the local bridge process, and the user's connection row
+in Design (which the browser reads to authorize \`/live-edit-bridge\`,
+\`/read-file\`, \`/write-file\`). Get them to match by letting the
+**authenticated** \`open-visual-edit\` action mint the token, then starting the
+bridge with it. This is the only ordering that works for the remote-MCP flow —
+the bridge cannot push its own token to the server without a CLI auth token, so
+the server mints instead and the bridge adopts.
+
+From the target app repo, make sure its dev server is running, then:
+
+**1. Discover routes without starting a durable bridge** (one-shot, exits):
+
+\`\`\`bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+\`\`\`
+
+This prints the manifest (routes + capabilities). Parse it to build
+\`routeManifest\` for the next step. (Skip this if the user already gave explicit
+paths/URLs to place.)
+
+**2. Call \`open-visual-edit\`** (see Action Flow below) with NO \`bridgeToken\`.
+The server mints one, stores it on the user's connection row, copies it into the
+placed screens' metadata, and returns it to you as \`bridgeToken\`. Capture it.
+
+**3. Start the persistent bridge adopting that token** (single line; prefer the
+env var so the secret does not appear in \`ps\`):
+
+\`\`\`bash
+AGENT_NATIVE_BRIDGE_TOKEN="<bridgeToken from step 2>" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon
+\`\`\`
+
+(Equivalently, pass \`--bridge-token <token>\`.) This starts a detached bridge on
+\`http://127.0.0.1:7331\`, adopts the server-minted token — so bridge and row
+agree and live-edit authorizes with no self-registration — and stays alive after
+the command exits.
+
+For a manual health/manifest check on the running bridge:
+
+\`\`\`bash
+curl http://127.0.0.1:7331/manifest.json
+\`\`\`
+
+Only use \`--json\` for the step-1 route probe. Never use \`--json\`, \`--once\`,
+or \`--dry-run\` for the durable step-3 bridge: they print the manifest and exit,
+so Design falls back to a non-editable live iframe.
+
+## Action Flow
+
+Prefer the single authenticated \`open-visual-edit\` action. It registers or
+refreshes the localhost bridge connection, mints and stores the bridge token,
+creates or reuses a Design project, places URL-backed screens, stores the active
+visual-edit context, and navigates to overview mode in one call. This avoids
+creating a private design under a synthetic CLI user and then handing the browser
+a tokenized URL that may be shadowed by an existing session.
+
+Call it BEFORE starting the durable bridge (step 3 above): it does not contact
+the bridge, so the bridge need not be running yet, and you need its returned
+\`bridgeToken\` to start the bridge with a matching secret. Omit \`bridgeToken\`
+on the call so the server mints one.
+
+\`\`\`bash
+pnpm action open-visual-edit '{
+  "title": "Docs homepage visual edit",
+  "devServerUrl": "http://localhost:5173",
+  "bridgeUrl": "http://127.0.0.1:7331",
+  "rootPath": "/absolute/path/to/app",
+  "routeManifest": { "...": "from /manifest.json" },
+  "paths": ["/", "/pricing", "/checkout?step=payment"]
+}'
+\`\`\`
+
+The action returns \`designId\`, \`connectionId\`, \`bridgeToken\`, \`screens\`,
+\`urlPath\`, and \`openUrl\`. Keep \`designId\`/\`connectionId\` in the chat context
+for follow-ups, and pass \`bridgeToken\` to \`design connect\` (step 3) to start
+the bridge. On follow-up calls reusing an existing \`connectionId\`, the same
+token is returned (it is minted once and reused), so the running bridge stays
+valid.
+
+For a numbered flow the user describes in chat, keep the labels and order:
+
+\`\`\`bash
+pnpm action open-visual-edit '{
+  "designId": "<existing-design-id>",
+  "connectionId": "<existing-connection-id>",
+  "devServerUrl": "http://localhost:1234",
+  "routes": [
+    { "url": "localhost:1234/onboarding/1", "title": "Screen 1" },
+    { "url": "localhost:1234/onboarding/2", "title": "Screen 2" },
+    { "url": "localhost:1234/onboarding/3", "title": "Screen 3" }
+  ]
+}'
+\`\`\`
+
+For responsive follow-ups, call \`open-visual-edit\` again with the same
+\`designId\` and \`connectionId\`, plus explicit viewport dimensions:
+
+\`\`\`bash
+pnpm action open-visual-edit '{
+  "designId": "<existing-design-id>",
+  "connectionId": "<existing-connection-id>",
+  "devServerUrl": "http://localhost:5173",
+  "paths": ["/"],
+  "defaultWidth": 390,
+  "defaultHeight": 844,
+  "startX": 1600,
+  "startY": 0
+}'
+\`\`\`
+
+If no \`routes\` or \`paths\` are supplied, \`open-visual-edit\` uses every route
+from the localhost manifest.
+
+Fallback, only when \`open-visual-edit\` is unavailable:
+
+1. Register or refresh the bridge with \`connect-localhost\`, passing the
+   \`/manifest.json\` result as \`routeManifest\` and \`capabilities\`.
+2. Create or reuse a Design project with \`create-design\`.
+3. Place URL-backed screens with \`add-localhost-screens\`.
+4. Navigate to overview mode with \`navigate\`.
+
+## Open The Design Surface
+
+- Use the \`link\`, \`deepLink\`, or MCP App embed returned by Design actions so
+  the user sees the canvas. In Codex Desktop or VS Code, prefer opening that
+  Design URL in the available preview/webview panel; otherwise surface the
+  "Open design" link.
+- Return or open the \`openUrl\` / action link, not a hand-built
+  \`/design/:id?_session=...\` URL.
+- If the user is working in VS Code, the Agent Native extension can open the
+  same URL via
+  \`vscode://builder.agent-native/open?url=<encoded-design-url>\`. Its
+  \`Agent Native: Open Design Canvas\` command also starts the local bridge and
+  opens hosted Design in the VS Code side panel.
+- After \`add-localhost-screens\`, confirm the Design editor is in overview mode
+  with the requested URL-backed frames visible. Do not stop at "screens added"
+  when the user asked to inspect or edit visually.
+
+## Editing URLs
+
+Keep localhost screens as URL files plus \`screenMetadata[fileId]\`. Do not
+replace them with copied \`srcdoc\` HTML unless the user explicitly asks for a
+frozen snapshot. To change a state, rerun \`add-localhost-screens\` with the new
+path/query or duplicate the screen and update the copy's URL metadata.
+
+## React Source Writeback
+
+- Use compiler/debug provenance (project-relative file, line, column,
+  component, and runtime multiplicity) to locate React/TSX source. Treat it as
+  evidence, not as permission for a generic AST structural transform.
+- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
+  \`.map()\` instances, shared components, and cross-file changes go through the
+  coding agent with exact subject/target anchors and their runtime
+  relationship.
+- Before each write, read the file and pass its exact \`versionHash\` to
+  \`write-local-file\` with \`requireExpectedVersionHash: true\`; on conflict,
+  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms
+  the result. Human write consent remains mandatory and agents cannot grant it.
+
+## Verification
+
+- \`list-localhost-connections\` returns the expected connection and routes.
+- The Design editor opens in overview mode.
+- Every requested screen renders the intended localhost URL.
+- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
+`;