@agent-native/core 0.122.4 → 0.123.0

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -28,7 +28,7 @@ exported instructions only, with no MCP connector registration.
 ## Core Model
 
 - Each screen is a URL-backed iframe, not copied HTML.
-- Each screen keeps its own URL metadata: `connectionId`, `routeId`, `path`,
+- Each screen keeps URL metadata: `connectionId`, `routeId`, `path`,
   `url`, `bridgeUrl`, title, and viewport size.
 - Localhost Edit mode renders the running app through the local bridge as a live
   iframe with the same editor bridge used by HTML designs. It is not a frozen
@@ -43,18 +43,16 @@ exported instructions only, with no MCP connector registration.
 - While a localhost screen has pending live visual edits, do not switch back to
   Interact until the user either applies the edits to source or explicitly
   aborts/discards the preview.
-- Start in Design's screen overview mode. The user can edit/select/drop on any
-  visible screen from the overview canvas.
-- In overview, screens are static like Figma frames: no iframe scrolling or app
-  interaction. Full-screen focus is for scrolling and app interaction.
+- 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 when you need a
-  new flow state.
-- Flow visualization is just multiple URL states: `/checkout?step=shipping`,
+  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`.
+  `localhost:1234/onboarding/1` means
+  `http://localhost:1234/onboarding/1`.
 
 ## Select And Reprompt
 
@@ -74,7 +72,7 @@ The UI previews the returned subtree without persisting it.
 Use `resolve-node-rewrite` for the accept/reject lifecycle. Accept applies the
 chosen variant as one version-checked inline/Yjs content transaction so one
 undo restores the prior structure; reject clears the proposal without changing
-content. For conversational resolution such as “apply the second one,” call
+content. For conversational resolution such as "apply the second one," call
 `view-screen`, read the active `design.reprompt.proposal`, and pass its
 `proposalId` plus the zero-based `variantIndex` to `resolve-node-rewrite`.
 
@@ -89,92 +87,172 @@ content. For conversational resolution such as “apply the second one,” call
 - 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
-(which the browser reads to authorize `/live-edit-bridge`, `/read-file`,
-`/write-file`). Let the authenticated `connect-localhost` / `open-visual-edit`
-action mint the token, then start the bridge adopting it — the bridge cannot
-push its own token to the server without a CLI auth token, so the server mints.
+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 a durable bridge** (one-shot, exits):
+**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
 ```
 
-Prints the manifest (routes + capabilities). Use it to build `routeManifest` for
-the action call. Skip if the user already gave explicit paths/URLs.
+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.)
+
+Inside the agent-native monorepo itself, use the workspace CLI instead of
+`npx` — `npx` installs the last published `@agent-native/core`, which will not
+contain local changes and costs a slow install on every call:
+
+```bash
+pnpm dev:cli design connect --url http://localhost:5173 --root templates/<app> --json
+```
+
+**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
+```
 
-**2. Register the connection** via `connect-localhost` / `open-visual-edit`
-(Action Flow below) with NO `bridgeToken`. The server mints one, stores it on the
-connection row, and returns it as `bridgeToken`. Capture it.
+(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.
 
-**3. Start the persistent bridge adopting that token:**
+For a manual health/manifest check on the running bridge:
 
 ```bash
-AGENT_NATIVE_BRIDGE_TOKEN="<bridgeToken from step 2>" \
-  npx @agent-native/core@latest design connect \
-  --url http://localhost:5173 --root . --daemon
+curl http://127.0.0.1:7331/health
 ```
 
-(Or pass `--bridge-token <token>`; prefer the env var to keep the secret out of
-`ps`.) The bridge exposes `GET /manifest.json`, `GET /routes.json`,
-`GET /health`, and now authorizes live-edit because its token matches the row.
+`/health` needs no token. The full manifest at `/manifest.json` is
+preview-token protected, so an unauthenticated `curl` of it returns
+`{"ok":false,"error":"invalid or missing preview token"}` — that response means
+the bridge is up, not that it is broken.
+
+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.
 
-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.
+The bridge listens on a single fixed port (7331) and refuses to start for a
+second, different app. It is detached with no log file, so if `--daemon` reports
+a timeout, check for a stale process (`lsof -ti:7331`) before retrying.
 
 ## Action Flow
 
-1. Register or refresh the bridge in Design:
+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 connect-localhost '{
+pnpm action open-visual-edit '{
+  "title": "Docs homepage visual edit",
   "devServerUrl": "http://localhost:5173",
   "bridgeUrl": "http://127.0.0.1:7331",
-  "rootPath": ".",
-  "routeManifest": { "version": 1, "sourceType": "localhost", "routes": [] }
+  "rootPath": "/absolute/path/to/app",
+  "routeManifest": { "...": "from /manifest.json" },
+  "paths": ["/", "/pricing", "/checkout?step=payment"]
 }'
 ```
 
-Prefer passing the actual `/manifest.json` result as `routeManifest` and
-`capabilities`. Keep any local filesystem paths out of user-facing summaries
-unless the user asks.
+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.
+
+### Desktop and mobile side by side
 
-2. Create or reuse a Design project:
+Pass `viewports` to place every requested route once per viewport. Frames lay
+out as a grid: one row per route, one column per viewport. Presets are
+`desktop` (1280x900), `laptop` (1440x900), `tablet` (834x1112), and `mobile`
+(390x844); an explicit `{ "label": "...", "width": N, "height": N }` also works.
 
 ```bash
-pnpm action create-design --title "Local app visual edit" --projectType prototype
+pnpm action open-visual-edit '{
+  "title": "Tasks responsive visual edit",
+  "devServerUrl": "http://localhost:5173",
+  "bridgeUrl": "http://127.0.0.1:7331",
+  "rootPath": "/absolute/path/to/app",
+  "paths": ["/tasks", "/inbox"],
+  "viewports": ["desktop", "mobile"]
+}'
 ```
 
-3. Place URL-backed screens on the overview canvas:
+Prefer this over two separate calls with `defaultWidth`/`defaultHeight`: it
+keeps each route's viewports aligned in a row and titles them
+`Tasks — Desktop` / `Tasks — Mobile` so the canvas reads clearly. `viewports`
+overrides `defaultWidth`/`defaultHeight`. With no `routes`/`paths`, it expands
+every route in the localhost manifest, which is usually far more frames than
+the user wants — name the paths.
+
+### Adding more page frames later
+
+Call `open-visual-edit` again with the same `designId` and `connectionId` and
+only the new paths. Existing frames for the same route and viewport are
+refreshed in place rather than duplicated, and a frame the user has dragged or
+resized keeps its position unless you explicitly pass `x`/`y`/`width`/`height`.
 
 ```bash
-pnpm action add-localhost-screens '{
-  "designId": "<design-id>",
-  "connectionId": "<connection-id>",
-  "routes": [
-    { "path": "/", "title": "Home", "width": 1280, "height": 900 },
-    { "path": "/pricing", "title": "Pricing", "width": 1280, "height": 900 },
-    { "path": "/checkout?step=payment", "title": "Checkout payment", "width": 1280, "height": 900 }
-  ],
-  "startX": 0,
-  "startY": 0,
-  "gap": 160
+pnpm action open-visual-edit '{
+  "designId": "<existing-design-id>",
+  "connectionId": "<existing-connection-id>",
+  "devServerUrl": "http://localhost:5173",
+  "paths": ["/settings", "/team"],
+  "startY": 2200
 }'
 ```
 
+Do NOT add `defaultWidth`/`defaultHeight` just to restate the default size:
+supplying either one marks the viewport as explicitly requested, which
+overwrites frame sizes the user has already adjusted on the canvas.
+
 For a numbered flow the user describes in chat, keep the labels and order:
 
 ```bash
-pnpm action add-localhost-screens '{
-  "designId": "<design-id>",
-  "connectionId": "<connection-id>",
+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" },
@@ -183,41 +261,57 @@ pnpm action add-localhost-screens '{
 }'
 ```
 
-If no `routes` or `paths` are supplied, `add-localhost-screens` uses every route
-from the latest localhost manifest. Use `paths` for a concise flow:
-
-```bash
-pnpm action add-localhost-screens '{
-  "designId": "<design-id>",
-  "paths": ["/", "/pricing", "/checkout?step=payment"]
-}'
-```
-
-4. Navigate the user to overview mode:
-
-```bash
-pnpm action navigate --view editor --designId "<design-id>" --editorView overview
-```
+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 `open-visual-edit`, confirm the Design editor is in overview mode
+  with the requested URL-backed frames visible, and that they render the app
+  rather than a spinner. Do not stop at "screens added" when the user asked to
+  inspect or edit visually.
+
+## Applying Visual Edits Back To Source
+
+Canvas edits on a localhost screen do not write source as you make them. They
+accumulate as pending edits and the editor shows an "Apply with Design agent"
+button in the bottom-right corner of the canvas. Clicking it hands a structured
+prompt to the Design agent chat, which performs the real source write.
+
+- Style, text, and drag/drop structure edits all collect into the same pending
+  batch, so the user can make several changes and apply once.
+- After the write lands, the target app's own dev-server HMR refreshes the
+  frames — no manual reload. If frames do not refresh, the write did not land;
+  say so rather than assuming.
+- The separate disk-icon "Apply to source" button is the deterministic
+  whole-file HTML/CSS writer. It is intentionally disabled for compiled
+  `.jsx`/`.tsx` routes — those must go through the agent path above.
 
 ## Editing URLs
 
-To change a localhost screen's URL, update that screen through
-`add-localhost-screens` again using the same route-derived filename/path or use
-normal Design screen duplication followed by a route/path update. Keep the file
-content as the absolute URL and keep `screenMetadata[fileId]` aligned:
-
-```json
-{
-  "sourceType": "localhost",
-  "previewState": "live",
-  "url": "http://localhost:5173/checkout?step=done",
-  "previewUrl": "http://localhost:5173/checkout?step=done",
-  "path": "/checkout?step=done"
-}
-```
-
-Do not replace localhost screens with copied `srcdoc` HTML unless the user
-explicitly asks to freeze a snapshot.
+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 `open-visual-edit` with the new
+path/query or duplicate the screen and update the copy's URL metadata.
 
 ## Local Files in the Code Tab
 
@@ -247,27 +341,32 @@ the connected app's text/code files through the bridge
 - Saves are conflict-checked against the file's on-disk version — a file that
   changed since it was read fails with a version conflict instead of being
   overwritten.
-- React/TSX canvas edits use build/debug provenance to locate the responsible
-  source. A single-instance leaf text edit, literal `className`/`class` edit, or
-  flat literal `style={{ ... }}` property may use `apply-visual-edit` with a
+
+## 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.
+- A single-instance leaf text edit, literal `className`/`class` edit, or flat
+  literal `style={{ ... }}` property may use `apply-visual-edit` with a
   `local-file` source and exact `target.sourceAnchor`. Preview first (omit
-  `persist`), inspect `proposedDiff`, then call with `persist: true`; the action
-  re-reads and writes through the consented, version-guarded local bridge.
-  Structural meaning still belongs to the coding agent. Do not apply a generic
-  AST reparent/group/ungroup transform. Repeated `.map()` instances, shared
-  components, dynamic expressions, breakpoint edits, and cross-file edits
-  always require semantic inspection.
-- For every semantic React write, read the file first, pass that exact
-  `versionHash` to `write-local-file` with `requireExpectedVersionHash: true`,
-  re-read and re-plan if it conflicts, and
-  verify the resulting HMR/runtime state before treating the preview as saved.
-  Human write consent remains mandatory and cannot be granted by an agent.
+  `persist`), inspect `proposedDiff`, then call with `persist: true`.
+- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
+  `.map()` instances, shared components, breakpoint-scoped edits, and
+  cross-file changes go through the coding agent with exact subject/target
+  anchors and their runtime relationship. `apply-visual-edit` refuses these
+  with `status: "needsAgent"` rather than guessing.
+- 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.
+- Every requested screen renders the intended localhost URL, showing real app
+  content rather than an endless loading spinner.
 - Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
 - 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.

package/corpus/templates/design/AGENTS.md

@@ -4,15 +4,45 @@ Design is an agent-native prototyping app. The agent creates and edits
 complete interactive HTML prototypes, design systems, variants, and handoff
 exports through actions against the shared SQL state.
 
+## Skills
+
 Keep this file essential — it is loaded into the agent's context every turn.
 Real depth lives in `.agents/skills/`; read the relevant skill before deeper
 work in that area.
 
+- `design-generation` — 5-phase generation flow, aesthetic quality bar, code
+  layers/code workspace, editor extensions, breakpoints/screen
+  states/components, motion, imagery, locked subtrees, generation state.
+- `design-templates` — resolving, saving, copying, adapting templates or prior
+  Design work without fresh generation.
+- `responsive-breakpoints` — Framer-style breakpoint editing.
+- `design-systems` — tokens, brand extraction, Figma import/read/paste, and the
+  real Figma fidelity contract.
+- `creative-context` — cross-app source reuse, pinned packs, provenance,
+  context opt-out, submitting a design to a governed Context.
+- `design-review-feedback` — persisted, element-anchored review comments to a
+  verified close, one root thread at a time.
+- `export-handoff` — HTML/PNG/SVG/ZIP/code and coding-handoff export.
+- `visual-edit` — editing a real local app visually (localhost bridge, Code
+  tab, reprompt write boundary).
+- `full-app-build` — design source modes and flag-gated fusion-backed full app
+  building.
+- `shader-fills` — code-backed GLSL shader fills/effects.
+- `sharing` — design and design-system visibility/grants.
+- `frontend-design`, `shadcn-ui` for UI; `actions`, `delegate-to-agent`,
+  `security`, `self-modifying-code` for framework patterns.
+
 Before building common workspace or agent UI, read `agent-native-toolkit` to
 inventory existing public kits and installed package seams. Use
 `customizing-agent-native` for the configure → compose → eject → propose seam
 ladder.
 
+## Actions
+
+- Resolve templates or prior designs with `list-design-templates` and
+  `list-designs`, copy with `create-design-from-template`, then inspect and
+  adapt copied files with `get-design-snapshot` and `edit-design`.
+
 ## Core Rules
 
 - Store large file/blob payloads in configured file/blob storage, not SQL: no
@@ -24,58 +54,42 @@ ladder.
   secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.
-- A message beginning with `[Reprompt selection]` is preview-only: call
-  `propose-node-rewrite` with its exact `repromptId`, target, and base hash;
-  never call a content writer (`edit-design`, `generate-design`,
-  `apply-visual-edit`, ...) — only the frontend-only `resolve-node-rewrite`
-  persists an accepted proposal (see `visual-edit`'s "Select And Reprompt").
-  `[Selection question]` is read-only: answer about the captured element and
-  subtree without calling content-writing actions.
+- A message beginning with `[Reprompt selection]` is preview-only: the only
+  mutation path is `propose-node-rewrite`; never call a content writer. See
+  `visual-edit`'s "Select And Reprompt". `[Selection question]` is read-only:
+  answer about the captured element and subtree without calling
+  content-writing actions.
 - Call `view-screen` before editing a specific design if the current design or
   selected file is not already clear from context.
 - Generated files must be complete, standalone HTML (Alpine.js + Tailwind CDN)
   that renders in the iframe without a build step. See `design-generation` for
-  the full generation workflow — phases, the aesthetic quality bar, and the
-  audit/screenshot pass required before calling a design "ready".
-- Treat `data-agent-native-locked="true"` as authoritative: locked elements
-  and descendants stay byte-for-byte unchanged (server-enforced). Ask the user
-  to unlock the layer in the Layers panel if they want it changed.
-- Figma import/read/paste and design-system/token workflows
-  (`import-figma-frame`, `get-figma-design-context`, `list-figma-library-assets`,
-  clipboard paste, `.fig` upload) are fully covered in `design-systems` — read
-  it before guessing the calling convention. Never claim universal lossless
-  Figma import/export; consult `FIGMA_INTEROPERABILITY.md` for the real
-  fidelity contract. For open-ended GitHub/Figma API questions, use
-  `provider-api-catalog`/`provider-api-docs`/`provider-api-request` rather than
-  treating provider actions as a capability ceiling; non-read Figma requests
-  need human approval.
+  the phases, quality bar, and the audit/screenshot pass required before
+  calling a design "ready".
+- Treat `data-agent-native-locked="true"` as authoritative — see
+  `design-generation` for locked-subtree rules.
+- Figma import/read/paste and design-system/token workflows are fully covered in
+  `design-systems` — read it before guessing the calling convention, and never
+  promise lossless Figma import/export.
 - Persist useful work early: create/update the design and files as soon as a
   coherent candidate exists, then iterate.
 - In dev, call actions with `pnpm action <name>`; in production, call the
   native tool.
-- For shared prototype feedback, use the persisted review actions
-  (`get-review-feedback`, `create-review-comment`, `resolve-review-thread`, ...)
-  — read `design-review-feedback` for the one-thread-at-a-time loop.
+- For shared prototype feedback, use the persisted review actions — read
+  `design-review-feedback` for the loop.
 - Follow linked design-system tokens and `customInstructions` whenever
   present; explicit user instructions in the current turn still win. Before
   generation, follow the `creative-context` reuse ladder and respect
-  `contextMode: "off"` without silently restoring a pack.
-- When the user references a template or prior design, call
-  `list-design-templates`/`list-designs`; use `create-design-from-template` and
-  `get-design-snapshot` before `edit-design`.
-- Design source modes are `inline` (current SQL-backed default), `localhost`
-  (`visual-edit`), and `fusion` (flag-gated, `full-app-build`). Preserve a
-  design's `fusionApp`/localhost connection data verbatim; never invent it.
-  Public `/visual-edit` and `/design/:id` links can render read-only without a
-  session — never run anonymous write actions (save/share/generate/localhost
-  connect); send signed-out visitors through
-  `/_agent-native/sign-in?return=...` first.
-- For multi-variant exploration, use `present-design-variants` (2-5 variants,
-  three by default) — see `design-generation` Phase 2 for the full
-  pick → delete-unchosen → refine flow; never call `generate-design` after a
-  variant pick.
-- When the user asks to download/export, use the export actions or point to
-  the editor download menu — see `export-handoff`.
+  `contextMode: "off"`.
+- When the user references a template or prior design, resolve it first — see
+  `design-templates` for the lookup and reuse order.
+- Design source modes are `inline`, `localhost`, and `fusion` — see
+  `full-app-build`. Public `/visual-edit` and `/design/:id` links can render
+  read-only without a session — never run anonymous write actions
+  (save/share/generate/localhost connect); send signed-out visitors through
+  `buildSignInReturnHref()` first.
+- For multi-variant exploration, use `present-design-variants` (2-5, three by
+  default) — see `design-generation` Phase 2 for the pick → refine flow.
+- When the user asks to download/export, see `export-handoff`.
 
 ## Application State
 
@@ -83,37 +97,10 @@ ladder.
 - `navigate` — moves the UI; auto-deleted after the client consumes it.
 - `design-selection` — active screen, selected element, overview mode,
   inspector tab, zoom, and screen list for the current tab.
-- `design-generation-session:<designId>` — multi-screen generation planning
-  state from `generate-screens` (canvas region assignments, per-frame
-  instructions consumed by `generate-design`).
+- `design-generation-session:<designId>`, `show-questions`, `guided-questions` —
+  generation planning, pre-generation questions, and the variant chat choice;
+  see `design-generation`.
 - `design-reprompt-pending:<designId>:<fileId>` /
   `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` — the
   compare-and-set reprompt request/proposal pair; see `visual-edit`'s
   "Select And Reprompt" for the full lifecycle.
-- `show-design-questions` opens pre-generation questions in the main canvas
-  (`show-questions` state). `guided-questions` may hold a one-click chat
-  choice for the current variant set.
-
-## Skills
-
-Read the relevant skill before deeper work:
-
-- `design-generation` — 5-phase generation flow, aesthetic quality bar, code
-  layers/code workspace, editor extensions, breakpoints/screen
-  states/components, motion, imagery.
-- `design-templates` — resolving, saving, copying, adapting templates or prior
-  Design work without fresh generation.
-- `responsive-breakpoints` — Framer-style breakpoint editing.
-- `design-systems` — tokens, brand extraction, and Figma import/read.
-- `creative-context` — cross-app source reuse, pinned packs, provenance,
-  context opt-out, submitting a design to a governed Context.
-- `design-review-feedback` — persisted, element-anchored review comments to a
-  verified close.
-- `export-handoff` — HTML/PNG/SVG/ZIP/code and coding-handoff export.
-- `visual-edit` — editing a real local app visually (localhost bridge, Code
-  tab, reprompt write boundary).
-- `full-app-build` — flag-gated fusion-backed full app building.
-- `shader-fills` — code-backed GLSL shader fills/effects.
-- `sharing` — design and design-system visibility/grants.
-- `frontend-design`, `shadcn-ui` for UI; `actions`, `delegate-to-agent`,
-  `security`, `self-modifying-code` for framework patterns.