@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -110,6 +110,50 @@ Pick a preset by `projectType`:
   `:root` CSS variable. Never hardcode `text-white` / `bg-black` / hex literals
   in the markup — that's what keeps brand + multi-screen consistency automatic.
 
+### Type-scale recipe
+
+Use this as a starting scale, then adjust to the chosen Aesthetic:
+
+- Display: 56-96px · H1: 40-64px · H2: 28-36px · Body: 16-18px · Caption: 12-13px.
+- Each adjacent step should be at least 1.25× the one below it — smaller jumps
+  read as "almost the same size" rather than a deliberate hierarchy.
+- A hero/display line should be at least 3× the body size.
+- Line-heights: display/H1 tight at 1.05-1.15, H2/H3 at 1.2-1.3, body relaxed
+  at 1.5-1.7.
+- Measure (line length) for body copy: 60-75 characters; constrain with
+  `max-width` in `ch` units, not a raw pixel guess.
+
+### Section rhythm
+
+Pick one section padding value and repeat it for every top-level section on
+the page/screen: 96-128px on desktop, 48-64px on mobile. Don't let each
+section invent its own padding — that's what makes a page feel unplanned.
+Use spacing to encode grouping: gaps *inside* a card or cluster should be
+visibly smaller than the gap *between* cards/sections — if inside-group and
+between-group spacing match, the eye can't tell where one group ends and the
+next begins.
+
+### Verifiable contrast pairs
+
+Don't just assert "WCAG AA" — check the actual token pairs the design ships.
+The most common real failure is muted text (`--color-text-muted`) directly on
+a card/surface background rather than the page background; verify that pair
+specifically, not just text-on-page. If an accent color doubles as text (a
+link, an active nav item, a price), it usually fails 4.5:1 against typical
+surfaces — add a separate `--color-accent-text` variant tuned for text-on-
+background contrast rather than reusing the decorative accent for copy.
+
+### Richer tokens
+
+Go beyond the minimal `:root` block in the HTML Structure Requirements below
+when the design needs it — add `--space-section` (see Section rhythm),
+`--color-border`, `--color-accent-text` (see contrast pairs above),
+`--shadow-card`, and a success/warning/danger trio
+(`--color-success` / `--color-warning` / `--color-danger`) once the design has
+status states, alerts, or form validation to express. Keep font tokens as
+placeholders you fill per design (see HTML Structure Requirements) rather than
+hardcoding a concrete family in a shared template.
+
 ## Building on existing code, screens, or a design system
 
 When a design system, tokens, current screens, or a connected codebase already
@@ -127,7 +171,7 @@ defaults. The banned-defaults list above still applies, plus:
   your colors". Keep structure and layout genuinely varied per screen while the
   palette, type, and components stay on-brand.
 
-## Generation Workflow — the canonical 4-phase flow
+## Generation Workflow — the canonical 5-phase flow
 
 This flow mirrors Claude Design's UX: ask → show variants → user picks → refine. Don't skip phases for new designs.
 
@@ -204,12 +248,21 @@ pnpm action generate-design \
 
 `generate-design` accepts a `--tweaks` array — pass 3-6 of the most impactful knobs bound to CSS custom properties the design's `:root` block actually defines. Surface controls users will actually want to adjust (accent color, density, radius, dark-mode toggle, font choice). Don't ship a generic preset; let the design's structure pick the knobs.
 
-### Phase 5 — Review before calling it ready
+### Phase 5 — Audit, fix, and eyeball before calling it ready
+
+Run `run-design-audit` against each screen (`designId` + `fileId`/`filename`).
+It returns `A11yFinding[]` covering missing alt/labels, tap-target size,
+focus-visibility, reduced-motion coverage, and a contrast hint. For every
+`error`-severity finding with `fixAvailable: true`, call `apply-a11y-fix`;
+for findings that aren't auto-fixable (missing alt text, structural issues),
+fix them directly with `edit-design`. **A design with audit errors is not
+ready** — don't report a design as done while `run-design-audit` still
+returns unresolved errors.
 
-Open the generated screen or overview and inspect it like a design review:
-hierarchy, overflow, mobile fit, contrast, keyboard focus, empty/loading/error
-states for app UI, and whether the copy/content still sounds real. Fix obvious
-issues before reporting the design as ready.
+After the audit is clean, do one visual pass by eye at both a mobile width
+(375px) and a desktop width (1280px): check for overflow/clipping, broken
+hierarchy, empty/loading/error states for app UI, and whether the copy/content
+still sounds real. Fix obvious issues before reporting the design as ready.
 
 ## HTML Structure Requirements
 
@@ -247,8 +300,8 @@ Every `index.html` must include:
       --color-surface: #1E293B;
       --color-text: #F8FAFC;
       --color-text-muted: #94A3B8;
-      --font-heading: 'Space Grotesk', sans-serif;
-      --font-body: 'DM Sans', sans-serif;
+      --font-heading: '<HEADING_FONT>', sans-serif; /* pick per Font Recommendations below — do not default to Space Grotesk */
+      --font-body: '<BODY_FONT>', sans-serif; /* pick a pairing, not a repeat of every other generation */
       --radius: 12px;
     }
 
@@ -484,11 +537,20 @@ to the chosen Aesthetic layer is what keeps designs from sharing a fingerprint:
 | Space Grotesk | DM Sans | Modern tech |
 | Playfair Display | Source Sans 3 | Editorial luxury |
 | Sora | Outfit | Clean geometric |
-| Cabinet Grotesk | Satoshi | Contemporary startup |
+| Bricolage Grotesque | Schibsted Grotesk | Contemporary startup |
 | Fraunces | Work Sans | Warm editorial |
 | JetBrains Mono | IBM Plex Sans | Developer tool |
-| Clash Display | General Sans | Bold statement |
+| Unbounded | Sora | Bold statement |
 | Archivo | Nunito Sans | Friendly SaaS |
+| Instrument Serif | Schibsted Grotesk | Editorial minimal |
+
+All of the above are served by Google Fonts (`fonts.googleapis.com/css2`). The
+mandatory `<head>` only loads the Google Fonts CDN (see HTML Structure
+Requirements) — Fontshare-only families (Cabinet Grotesk, Satoshi, Clash
+Display, General Sans) are not on Google Fonts and will silently fail to load,
+so the browser falls back to a system sans and quietly reintroduces the exact
+slop this skill bans. Only use a Fontshare family if you also add its
+Fontshare `<link>`/`@import` and confirm it renders.
 
 ## Multi-screen prototypes & navigation
 
@@ -569,7 +631,122 @@ regeneration is slow, expensive, and regresses unrelated parts.
 - Never use `<script>` blocks with raw DOM manipulation — use Alpine.js directives
 - Never inline `onclick="..."` handlers — use `@click`
 - Never use `!important` except in `[x-cloak]`
-- Never use position: fixed for modals — wrap in a portal-like pattern with Alpine.js
 - Never forget `cursor-pointer` on interactive elements
-- Never use `<img>` with placeholder URLs — use colored divs or gradients
-- Never set font-size below 14px for body text or 12px for labels
+- Never use `<img>` with placeholder/stock URLs — generate real imagery (see
+  Imagery below) or use tokened colored divs/gradients only for pure UI
+  chrome (icons, avatars-as-initials, decorative fills), never as a stand-in
+  for a hero, product shot, or portrait that should be a generated image
+- Never set font-size below 16px for body text or 12px for labels
+
+## Multi-screen consistency contract
+
+When a design has more than one screen, the shared system must be
+byte-identical across every screen file, not just similar: the `:root` token
+block, the Google Fonts `<link>`, the nav, and the footer should match exactly
+between `index.html` and every other screen. Before saving a new or edited
+screen, diff its `:root` block against `index.html`'s (or the design system's
+tokens) and reconcile any drift instead of letting each screen accumulate its
+own slightly-different palette. Consistency is not sameness — keep structure
+and layout varied per screen (see "Building on existing code" above) while the
+token layer, typography, nav, and footer stay identical.
+
+## Breakpoints & screen states
+
+- **Breakpoints**: `add-breakpoint` adds a device-width frame (Mobile 390 /
+  Tablet 768 / Desktop 1280, or a custom width) to the design's breakpoint set
+  stored in `designs.data`; the Tailwind prefix is derived from the width and
+  duplicate widths are ignored. `remove-breakpoint` removes one by id.
+  `set-active-breakpoint` sets which frame is the current edit scope — editing
+  a layer while `base` is active writes unprefixed Tailwind classes, editing
+  while `md` is active writes `md:`-prefixed classes. Always check the active
+  breakpoint before making a responsive-only edit so the class lands at the
+  right prefix.
+- **Design states**: `create-design-state` creates a named alternate
+  DOM/Alpine snapshot (`kind: "state"` — Loading, Empty, Error), a static data
+  fixture (`kind: "fixture"`), or a placeholder for a live capture
+  (`kind: "capture"`). `apply-design-state` updates an existing state row
+  (rename, change breakpoint, update fixture/capture data, set the preview
+  reference). `capture-design-state` records a running app's current route,
+  props, and API data into a `capture` row — it requires the design's source
+  to advertise the `captureState` bridge capability (localhost/fusion); for
+  inline designs without a live bridge, use `create-design-state` instead.
+  `list-design-states` lists all states/fixtures/captures for a design, and
+  `delete-design-state` removes one (irreversible; the design itself is
+  unaffected).
+
+## Component reuse
+
+Before hand-rolling another near-duplicate card/button/nav item, check
+whether the pattern already exists as a recognised component. Once a visual
+pattern repeats 3+ times in a design, promote it: call `create-component` on
+the selected root element to stamp deterministic
+`data-agent-native-component="<Name>"` and `data-agent-native-prop-*`
+annotations, so it becomes a recognised component instance for the canvas
+outline and the Component inspector section. Use `index-components` to scan a
+design's HTML for existing `data-agent-native-component` annotations and
+persist the discovered component list before inventing something that may
+already exist. `get-component-details` returns a selected instance's name,
+props, variants, and source info. `preview-component-prop-edit` previews a
+prop/class change on the canvas without saving; `apply-component-prop-edit`
+persists it. `open-component-source` navigates to the component's source
+location (the design file for inline/Alpine designs, or the resolved external
+file for localhost/fusion sources).
+
+## Realistic app-state content
+
+For app/product UI (not marketing pages), populate lists and tables with
+plausible mid-life data — not a pristine "just signed up" empty account and
+not obviously fake placeholder rows (avoid "Lorem Ipsum User", "Item 1", "Item
+2"). Include at least one realistically long name/title/label so truncation
+and wrapping behavior is visible. Always design the empty state and a loading
+skeleton for the screen's primary data surface — don't only show the
+happy-path populated state.
+
+## Motion craft
+
+Push motion the same way you push type and color: on purpose, not as a
+uniform default. Duration bands: 150-250ms for micro-interactions (hover,
+toggle, button press), 300-500ms for panel/sheet/modal transitions, and
+500-800ms reserved for exactly one orchestrated page-load reveal (stagger
+individual elements 60-100ms apart, capped at about 6 staggered elements —
+more than that reads as sluggish, not polished). Ease functions: `ease-out`
+for elements entering, `ease-in` for elements leaving. Animate only
+`transform` and `opacity` for performance; avoid animating `width`/`height`/
+`top`/`left`. Every non-essential animation must respect
+`prefers-reduced-motion` (see the mandatory `<style>` block below). For
+inline/Alpine screens, persist motion as durable timeline metadata: inspect
+the current file's timeline with `get-motion-timeline`, then write changes
+with `apply-motion-edit` using the same `sourceRef`/`fileId` — this is not a
+one-way export, edits stay editable.
+
+## Imagery
+
+Generate real images for anything a real product would photograph or
+illustrate: hero backgrounds, product shots, portraits/avatars, testimonial
+photos, marketing/editorial imagery. Don't generate images for utility UI —
+icons, data tables, form chrome, and dashboard widgets should stay as
+tokened SVG/CSS, not photos.
+
+- **Use the Assets generation tool** (`generate-asset`, or `insert-asset` once
+  an asset is chosen) instead of `<img>` placeholder URLs or colored-div
+  stand-ins. See the Core Rules image-generation bullet in `AGENTS.md` for the
+  full calling convention (default `tier: "fast"`, `callerAppId: "design"`,
+  matching `aspectRatio`).
+- **Write image prompts as art direction, not a one-line label.** Specify
+  subject, composition, lens/framing, lighting, and palette, and tie the
+  palette/mood back to the design's own `:root` tokens so the image reads as
+  part of the same system rather than a stock photo dropped in. If a design
+  system is linked, fold its `imageStyle.styleDescription` into the prompt
+  (see `design-systems` skill) so generated imagery matches the brand's
+  established photographic/illustration style.
+- **Default to `tier: "fast"`** (the cheap Gemini Flash "nanobanana"-class
+  model) for exploration and every non-final variant. Only request
+  `tier: "best"` for the final, user-approved hero image — not for every pass.
+- **Match `aspectRatio` to the layout slot**: `21:9` for a full-bleed hero,
+  `4:3` for a card/feature image, `1:1` for an avatar or square thumbnail.
+  Mismatched aspect ratios force ugly crops in the browser.
+- **Always write real `alt` text** describing the image's content — never
+  leave `alt=""` on a meaningful (non-decorative) image.
+- **Placement is a two-step pass**: call `insert-asset` to place the chosen
+  image, then do one `edit-design` pass to adjust surrounding layout/spacing
+  if the inserted figure doesn't sit flush with the rest of the design.

package/corpus/templates/design/.agents/skills/design-systems/SKILL.md

@@ -73,6 +73,12 @@ interface DesignSystemData {
 }
 ```
 
+`imageStyle.styleDescription` is not just metadata — fold it into every
+`generate-asset` prompt for a design linked to this system, alongside the
+subject/composition/lighting direction described in the design-generation
+skill's Imagery section. This is what keeps generated photography/illustration
+on-brand instead of drifting to a generic stock look each time.
+
 ## Actions
 
 ### Creating a Design System
@@ -92,8 +98,8 @@ pnpm action create-design-system \
       "textMuted": "#94A3B8"
     },
     "typography": {
-      "headingFont": "Space Grotesk",
-      "bodyFont": "DM Sans",
+      "headingFont": "<HEADING_FONT>",
+      "bodyFont": "<BODY_FONT>",
       "headingWeight": "700",
       "bodyWeight": "400",
       "headingSizes": { "h1": "64px", "h2": "40px", "h3": "28px" }
@@ -105,6 +111,12 @@ pnpm action create-design-system \
   }'
 ```
 
+`<HEADING_FONT>` / `<BODY_FONT>` are placeholders — pick a real Google Fonts
+pairing per the design-generation skill's Font Recommendations table (or the
+brand's actual extracted fonts) rather than defaulting to Space Grotesk/DM
+Sans every time; that pairing is this skill's own most common convergence
+fingerprint.
+
 If this is the user's first design system, it is automatically set as the default.
 
 ### Reading a Design System
@@ -257,8 +269,8 @@ When the user provides multiple sources, call all applicable import actions in p
 4. **Documents supplement** — presentations may reveal brand colors not in code
 5. **Images inform mood** — color temperature, density, visual style
 6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve conflicts
-6. **Call `create-design-system`** with the combined result
-7. **Link to design** via `update-design --designSystemId`
+7. **Call `create-design-system`** with the combined result
+8. **Link to design** via `update-design --designSystemId`
 
 ## Applying Design System to Generated HTML
 

package/corpus/templates/design/.agents/skills/export-handoff/SKILL.md

@@ -10,6 +10,24 @@ description: >-
 
 How to export designs and generate handoff documentation for developers converting prototypes to production code.
 
+## Other export actions
+
+- **SVG**: `export-svg` exports a design project as an SVG document (a
+  `foreignObject` wrapper around the standalone HTML), giving agent parity
+  with the editor's Download SVG command. The editor's own Download SVG
+  command captures the live browser DOM for the most faithful snapshot; use
+  the action when you need agent-side SVG export without a live browser.
+- **PNG**: there is no PNG export action. Point the user to the editor's
+  download menu (Download PNG) — PNG export is a client-side rasterization of
+  the live canvas and is not exposed as an agent action.
+- **Deploy preview**: `deploy-design-preview` triggers a preview deploy for a
+  fusion-backed design branch. It requires the design's source to advertise
+  the `deployPreview` capability (fusion tier) and Builder.io to be connected;
+  a branch must already exist via `create-design-branch`. For inline/localhost
+  designs it returns `ctaRequired: true` with a Make-it-real CTA instead of
+  faking a deploy. This triggers a *preview* deploy only — production
+  publishing goes through the Builder Visual Editor's Publish flow.
+
 ## Export Formats
 
 ### HTML Export
@@ -70,9 +88,30 @@ pnpm action export-pdf --id <designId>
 
 Returns all design data and files needed for the client to render a PDF.
 
-## Claude Code Handoff
+## Coding Handoff
+
+When a user wants to convert an Alpine.js + Tailwind prototype into production
+code, use the canonical `export-coding-handoff` action instead of hand-writing
+a handoff message:
+
+```bash
+pnpm action export-coding-handoff --id <designId>
+```
+
+This returns tokenized raw and ZIP URLs any external coding agent can fetch,
+plus a ready-to-copy prompt. The bundle reflects the design's **current**
+state — live editor (collab) content plus the user's applied visual tweaks
+resolved into the HTML `:root` — so the generated code matches what the user
+actually tuned, not the original generated tokens. Pass `format: "json"` if the
+receiving agent wants structured data instead of markdown, and `origin` to get
+an absolute raw-code URL for a specific app origin. This is the canonical
+design-to-code tool; prefer it over composing a handoff message by hand.
+
+### Manual handoff template (fallback)
 
-When a user wants to convert an Alpine.js + Tailwind prototype into production code, generate a detailed handoff prompt. This is not an action — it is a structured message you compose based on the design.
+Use the template below only when `export-coding-handoff` isn't available or
+the user explicitly wants a hand-composed summary instead of the action's
+bundle. Compose it based on the design's actual HTML/tokens.
 
 ### Handoff Prompt Template
 
@@ -159,7 +198,11 @@ pnpm action export-html --id [designId]
 
 ### Generating the Handoff
 
-When the user asks to "hand off" or "convert to production code":
+When the user asks to "hand off" or "convert to production code", call
+`export-coding-handoff --id <designId>` first (see Coding Handoff above) — it
+already extracts tokens, resolves applied tweaks, and returns a ready-to-copy
+prompt plus fetchable URLs. Only fall back to composing the manual template
+by hand if that action is unavailable:
 
 1. Read the design: `get-design --id <designId>`
 2. Extract all CSS custom properties from the HTML

package/corpus/templates/design/.agents/skills/full-app-build/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: full-app-build
+description: >-
+  Build and iterate on a full real app from Design, backed by a running
+  Builder Fusion cloud container instead of an inline HTML prototype. Use
+  when the user wants a real/full app end-to-end through publishing, and
+  only when FULL_APP_BUILDING_ENABLED is true.
+metadata:
+  visibility: exported
+---
+
+# Full App Building
+
+Full app building turns a Design project into a real, running app instead of
+an inline Alpine/HTML prototype. The source of truth is a live dev server
+inside a Builder Fusion cloud container — one Builder project branch per
+design. Screens are URL-backed iframes of that container's dev server, the
+same model as `/visual-edit` localhost screens (`sourceType: "fusion"`), but
+the container runs remotely instead of on the user's machine.
+
+## Flag Gate
+
+This feature is gated by the code boolean `FULL_APP_BUILDING_ENABLED` in
+`templates/design/shared/full-app.ts`, currently `false`. Check it (or trust
+that the fusion actions are unavailable/erroring) before proposing this flow.
+If the flag is off, tell the user full app building isn't enabled yet instead
+of attempting the actions.
+
+Even when the flag is on, the fusion actions require Builder credentials and
+a configured branch project ID. When those aren't set up, actions return a
+`not-configured` CTA instead of throwing — see **Not Configured** below.
+
+## When To Use
+
+Reach for full app building only when the user wants a real, working app —
+not a prototype — and wants to go end-to-end through publishing: real
+routing, real backend behavior, a deployable URL. For UI exploration, visual
+review, and iteration on look/feel, stay in the normal inline design flow
+(`design-generation`) or `/visual-edit` for connecting an existing local app.
+Do not switch a normal design into fusion mode unless the user explicitly
+asks for a full/real app.
+
+## Lifecycle
+
+1. **Create the design shell** the normal way (`create-design`), or continue
+   from an existing design.
+2. **`create-fusion-app`** `{designId, prompt, branchName?}` creates the app
+   branch via the Builder cloud agent. Returns
+   `{status: "building", projectId, branchName, editorUrl}` once started, or
+   the not-configured CTA. One branch per design — calling it again on an
+   already-linked design returns the existing linkage instead of creating a
+   second branch.
+3. **Poll `sync-fusion-app`** `{designId, paths?}` while the container boots.
+   It attaches to the container and reports `status: building|ready|error`.
+   Tell the user the app is building and keep polling — don't block on a
+   single call. Once `ready`, it updates `previewUrl` and upserts URL-backed
+   screens (default path `"/"` when `paths` is omitted).
+4. **Screens appear as URL-backed artboards** in the overview canvas, same
+   as localhost screens: iframe of `previewUrl` + route, not copied HTML.
+5. **Iterate** using the editing rules below, then push and publish when
+   ready.
+
+## Editing Rules — the critical distinction
+
+Fusion screens are NOT inline HTML files. **Never** edit a fusion screen's
+markup directly and never use `generate-design`, `edit-design`, or
+`apply-visual-edit` on it — those tools rewrite inline `design_files` rows,
+which fusion screens don't have. Writing to the wrong layer silently does
+nothing to the running app.
+
+Instead:
+
+- **`queue-fusion-edit`** `{designId, instruction, screenFileId?, target?}` —
+  queue one edit intent. Use `target` (`selector`, `path`, `url`, `nodeName`)
+  to point at the specific element/screen the user means, the same way you'd
+  describe a selection for `apply-visual-edit`. Queuing does not touch the
+  running app yet — it only records intent in `design_fusion_edits`.
+- **`list-fusion-edits`** `{designId, status?}` — inspect the queue before
+  dispatching, e.g. to confirm what's pending or to show the user a summary.
+- **`apply-fusion-edits`** `{designId, editIds?}` — batches all pending edits
+  (or the given `editIds`) into one prompt and dispatches it to the app's
+  in-container coding agent. This is fire-and-forget: it marks the edits
+  "sent" and returns immediately, it does not wait for the app agent to
+  finish.
+- **`send-fusion-message`** `{designId, prompt}` — for larger freeform
+  requests that don't fit the "queue small edits, batch them" model (new
+  features, structural changes, "wire up the backend for X"), relay a
+  message straight to the app's coding agent instead of queuing edits.
+
+After dispatching (`apply-fusion-edits` or `send-fusion-message`), tell the
+user the change was sent to the app's agent and is being applied
+asynchronously — it is not applied synchronously like an inline `edit-design`
+call. Screens reflect the change once the in-container agent finishes and the
+dev server updates; call `sync-fusion-app` again or have the user reload the
+screen to see it land.
+
+## Adding More Routes As Screens
+
+Once `previewUrl` is known (after `sync-fusion-app` reports `ready`), use
+**`add-fusion-screens`** `{designId, paths, width?, height?}` to place
+additional routes as screens on the overview canvas — the fusion equivalent
+of `add-localhost-screens`.
+
+## Push And Publish Flow
+
+1. **`push-fusion-app`** `{designId}` — pushes the branch's code to its git
+   remote. Do this before or as part of publishing so the code is durably
+   saved, not just running in the container.
+2. **`deploy-fusion-app`** `{designId, slug?}` — reserves
+   `<slug>.builder.cloud` (derived from the design title when `slug` is
+   omitted) and triggers a deploy.
+3. **`get-fusion-deploy-status`** `{designId}` — poll until the deploy status
+   is `live`, `failed`, or `canceled`. Report the live `deployedUrl` once it
+   resolves; report the failure reason if it doesn't.
+
+## Not Configured
+
+When Builder credentials or the branch project ID aren't set up, the fusion
+actions return a `not-configured` status with a `cta` object instead of
+throwing — mirror the guidance `migrate-inline-design-to-app` already gives:
+surface the CTA's `label`/`description` and point the user at
+`connect-builder-app` or the given `connectUrl` to connect Builder, then
+retry the same fusion action. Don't silently fall back to an inline design in
+this case — tell the user full app building needs Builder connected first.
+
+## Timing Expectations
+
+Set expectations up front so polling doesn't read as broken:
+
+- Creating the app branch and booting the container can take a few minutes —
+  this is a real cloud container starting a real dev server, not an inline
+  HTML render. Keep polling `sync-fusion-app` and give the user a short
+  status update rather than going silent.
+- Edits are asynchronous. `apply-fusion-edits` and `send-fusion-message`
+  return as soon as the prompt is dispatched, not when the app agent finishes
+  making the change. Don't promise the screen updated instantly — remind the
+  user the app's agent is working on it and the screen will reflect the
+  change once it's done and the dev server picks it up.
+- Deploys also take real time; poll `get-fusion-deploy-status` rather than
+  assuming `deploy-fusion-app` finished the deploy synchronously.

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

@@ -163,6 +163,25 @@ content as the absolute URL and keep `screenMetadata[fileId]` aligned:
 Do not replace localhost screens with copied `srcdoc` HTML unless the user
 explicitly asks to freeze a snapshot.
 
+## Local Files in the Code Tab
+
+Once a connection is registered, the design editor's Code panel (left rail →
+Code, or `navigate --view editor --designId <id> --leftPanel code`) shows a
+local-files workspace root for that connection next to the design's own files.
+It lists the connected app's text/code files through the bridge
+(`list-local-files` / `read-local-file`); build output, `node_modules`,
+`.git`, and secret-looking paths (`.env*`, key files) are always excluded.
+
+- Browsing and reading need only editor access on the design plus the running
+  bridge.
+- Saving goes through `write-local-file`: the first save opens the
+  write-consent dialog (an 8-hour, folder-scoped grant) and retries
+  automatically once granted. Only text/code files are writable; secret paths
+  are always blocked.
+- 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.
+
 ## Verification
 
 - `list-localhost-connections` returns the expected connection and routes.
@@ -170,3 +189,4 @@ explicitly asks to freeze a snapshot.
 - Every requested screen renders the intended localhost URL.
 - 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.