@agent-native/core 0.121.1 → 0.122.0

package/corpus/templates/content/_gitignore

@@ -37,3 +37,4 @@ data/.sessions.json
 learnings.md
 
 .vercel/
+.agent-native/

package/corpus/templates/design/.agents/skills/creative-context/SKILL.md

@@ -122,3 +122,14 @@ For an app-created Design snapshot, use
 `clone-creative-context-design-native` instead. That typed action resolves the
 exact approved private file/Yjs payload and duplicates it through Design's
 native path. Generic context actions must never receive or return that payload.
+
+## Submitting to Creative Context
+
+To submit a design to a governed Creative Context, use the Context tab or
+`manage-context-membership`; it captures one immutable live design snapshot.
+Reuse only a returned opaque native clone reference through the Design clone
+action (`clone-creative-context-design-native` above) rather than re-deriving
+one from a screenshot or generic context item. Use `operation="submit-latest"`
+with a Library membership id when its native update status reports
+`update-available`, so the library entry advances to the design's current
+state instead of staying pinned to the original submission.

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

@@ -322,7 +322,7 @@ size. Avoid dense multi-line copy at these sizes regardless.
 
 ### Phase 4 — Always ship tweaks with the 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.
+`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. When a user asks to add a tweak control to an existing design, preserve the existing useful tweaks and add/update only the requested definitions — read the current file with `get-design-snapshot` first if source edits are needed, and persist the complete updated tweak list through `generate-design`.
 
 ### Phase 5 — Audit, screenshot, fix, and eyeball before calling it ready
 
@@ -347,7 +347,17 @@ instead — fall back to a careful read of the HTML plus the audit findings. The
 returned screenshot `url` is for human review (embed it as `![...](url)` in
 your reply); also still scan the rendered output yourself for anything the
 diagnostics don't catch — broken hierarchy, empty/loading/error states for app
-UI, and whether the copy/content still sounds real.
+UI, and whether the copy/content still sounds real. To compare two design
+snapshots/branches for a file-level visual diff (added/removed/modified) —
+e.g. after a large refactor or before/after a review pass — call
+`get-design-review` instead of eyeballing both versions.
+
+After generation or a broad update, leave the user in the screen overview
+(`navigate --view editor --editorView overview`) when the work involves
+multiple screens or artboard placement — it's the primary editing surface for
+selecting, moving, resizing, and entering focused single-screen editing via a
+frame's Interact button. Reserve single-screen mode as the default landing
+view only when the user asked to focus one specific screen.
 
 ## HTML Structure Requirements
 
@@ -698,6 +708,12 @@ regeneration is slow, expensive, and regresses unrelated parts.
    tokens in `:root` rather than touching every element.
 5. **Don't add unrequested features** during a refinement pass.
 
+For selecting/editing DOM elements as code layers (layer projection, the
+deterministic `apply-visual-edit` slice, and the semantic React/TSX handoff),
+read `references/code-layers.md`. For the VS Code-style source workbench
+(explorer, quick open, `list-source-files`/`apply-source-edit`), read
+`references/code-workspace.md`.
+
 ## Tailwind v4 + motion gotchas
 
 - **Gradients:** Tailwind v4 renamed the utilities. Use `bg-linear-to-r`,
@@ -792,6 +808,26 @@ 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).
 
+## Suggested auto layout
+
+For an absolute/freeform container, first measure its direct children and
+present the proposed direction, visual order, gap, four-side padding,
+alignment, and sizing — do not mutate source until the user applies the
+preview. Inline HTML/Alpine applies the reviewed proposal through one
+`apply-visual-edit`-backed content transaction so undo restores the exact
+prior structure. Local React uses the semantic source handoff (see
+`references/code-layers.md`, never generic AST rewriting), preserves nested
+absolute descendants and responsive logic, and applies the approved proposal
+as one reversible source edit.
+
+## Editor extensions
+
+Design editor extensions render in the right inspector slot
+`design.editor.inspector` (`create-extension` →
+`add-extension-slot-target` → `install-extension`). Read
+`references/editor-extensions.md` for the context shape and the AI-driven
+style/artboard change flow.
+
 ## Realistic app-state content
 
 For app/product UI (not marketing pages), populate lists and tables with
@@ -829,9 +865,13 @@ 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`).
+  stand-ins — for raster generation, restyling, or editing existing
+  screenshots/photos. Always pass `callerAppId: "design"`. If no Assets MCP
+  tool is available, use the first-party Assets app via `call-agent` with
+  agent `"assets"` when available. If the user attached an image, use its
+  hosted chat-attachment URL or call `upload-image` to create one before
+  delegating. If no image/upload provider is configured, say that specific
+  setup is needed and continue any non-image Design work separately.
 - **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
@@ -847,6 +887,8 @@ tokened SVG/CSS, not photos.
   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.
+- **Placement is a two-step pass**: when the Assets picker returns a selected
+  asset, preserve its `assetId`, `runId`, and URLs verbatim; call `insert-asset`
+  to place the chosen image, then do one `edit-design` pass (using
+  `get-design-snapshot` first) 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-generation/references/code-layers.md

@@ -0,0 +1,81 @@
+# Code Layers — Deterministic Edits vs. Coding-Agent Handoff
+
+Full mechanics for how selected-element edits get from a canvas selection to a
+persisted change, for both inline HTML/Alpine designs and localhost React/TSX
+screens. See the `design-generation` SKILL.md for when to reach for this vs.
+`edit-design`/`generate-design`, and the `visual-edit` skill for the localhost
+bridge itself.
+
+## Reading layer structure
+
+`get-code-layer-projection` reads inline HTML/JSX and returns selectable layer
+nodes, selectors, names, and edit intents for agent and UI workflows. This is
+the read side of the same model `apply-visual-edit` writes to.
+
+## Inline HTML/Alpine — deterministic edits
+
+`apply-visual-edit` supports deterministic local edits for HTML-backed code
+layers: text, classes, styles, attributes, source order, and small structural
+changes. Use it for selected-element edits before falling back to full
+`update-design` / `generate-design` rewrites.
+
+## Localhost React/TSX — narrow deterministic slice
+
+`apply-visual-edit` also supports a narrow deterministic slice for localhost
+JSX/TSX: single-instance leaf text, literal `className`/`class`, and flat
+literal `style={{ ... }}` properties. Pass `source.kind: "local-file"`,
+`designId`, `connectionId`, the verified project-relative `path`, and
+`intent.target.sourceAnchor`. Call once without `persist` and inspect
+`proposedDiff`; call again with `persist: true` only when it is exact. The
+action reads the current bridge version and writes through `write-local-file`,
+so human consent and compare-and-swap remain mandatory.
+
+For localhost React/TSX screens, treat compiler/debug metadata
+(project-relative source file, line, column, component, and runtime
+multiplicity) as evidence for locating source, not as permission to run a
+generic AST transform. Compiler tooling may verify an anchor, classify a
+literal edit, and validate syntax. Reparenting, grouping/ungrouping,
+wrappers, dynamic expressions, repeated `.map()` instances, shared
+components, and cross-file changes must be handed to the coding agent with
+both runtime relationships and exact source anchors so it can inspect the
+surrounding program semantics.
+
+### The coding-agent handoff contract
+
+A localhost React handoff must:
+
+1. Read each source file first.
+2. Write with the exact returned `versionHash` as `expectedVersionHash` and
+   `requireExpectedVersionHash: true` — this is a compare-and-swap: the write
+   is rejected if the file changed since the read.
+3. Re-read and re-plan on a version conflict rather than forcing the write.
+4. Leave the optimistic canvas preview in place until the dev server/HMR
+   confirms the runtime result.
+
+Never report a semantic canvas change as persisted merely because it was
+submitted to the coding agent — persistence is confirmed by the dev
+server/HMR picking up the change, not by the handoff call returning.
+
+## Layer naming
+
+Prefer `data-agent-native-layer-name="Readable name"` on meaningful elements.
+The projection uses it before semantic/text fallbacks, and layer renames
+should persist by updating that attribute. `data-code-layer-id` and similar
+ids are for selection stability, not display naming.
+
+## Node id stamping
+
+For inline/Alpine screens, stamp and preserve unique
+`data-agent-native-node-id` attributes on selectable DOM nodes. Treat
+generated CSS selectors as a compatibility fallback only. For localhost React
+screens, resolve through build-time source/debug metadata (stable generated
+ids, component name, file, and line) before falling back to selectors.
+
+## Summary of the split
+
+- Inline/Alpine screens continue to use deterministic HTML code-layer edits.
+- Localhost React/TSX screens use the semantic coding-agent handoff above;
+  deterministic direct React writes remain intentionally limited to the leaf
+  literal slice above and never include generic structural transforms,
+  breakpoint writes, dynamic expressions, repeated renders, shared component
+  definitions, generated/out-of-root paths, or remote URLs.

package/corpus/templates/design/.agents/skills/design-generation/references/code-workspace.md

@@ -0,0 +1,42 @@
+# Code Workspace — VS Code-Style Workbench
+
+The editor's left rail has a wide `code` panel: a VS Code-style workbench
+(`app/components/design/code-workbench/`) with an explorer, workspace search,
+editor tabs, quick open (⌘P), a command palette (⇧⌘P), and a status bar. Open
+it with `navigate --view editor --designId <id> --leftPanel code` and
+optionally pass `fileId`, `filename`, or `screen` to focus a file.
+
+## Explorer roots
+
+The explorer shows one root per workspace source:
+
+- The design's SQL-backed files (`designfs://<designId>/`, backend
+  `virtual-inline`) — always present.
+- One root per localhost connection referenced by the design's screens.
+  `list-local-files` / `read-local-file` proxy the `design connect` bridge;
+  writes go through `write-local-file` and its user-approved consent grant —
+  see the `visual-edit` skill for the full bridge/consent flow.
+
+## Formatting
+
+Inline design files are auto-formatted with Prettier the first time they are
+opened in the workbench, and the formatted result is persisted. Local files
+(the localhost root) are never auto-formatted.
+
+## Inline source actions
+
+- `list-source-files` inspects the inline source workspace; `read-source-file`
+  returns file contents. Preserve the returned `versionHash` before writing.
+- Do not return full file content from `view-screen`; it reports only active
+  code file metadata and dirty state.
+- `preview-source-edit` shows a diff without saving. `apply-source-edit` with
+  the prior `versionHash` saves either a full replace or an exact replace.
+  These update the same inline file state the UI uses — agent edits show up
+  live in open workbench buffers.
+- `resolve-selection-source` finds the best matching inline file
+  location/snippet for the user's current canvas selection.
+
+## Session state
+
+The workbench session (open tabs, active file, sidebar layout) persists per
+design in application state under `code-workbench:<designId>`.

package/corpus/templates/design/.agents/skills/design-generation/references/editor-extensions.md

@@ -0,0 +1,34 @@
+# Design Editor Inspector Extensions
+
+Design editor extensions render in the right inspector slot
+`design.editor.inspector`. See the root `extension-points` skill for the
+general slot mechanism (`window.slotContext`, `createExtension`,
+`add-extension-slot-target`, `install-extension`); this file covers what's
+specific to the Design inspector slot.
+
+## Creating one
+
+1. `create-extension`
+2. `add-extension-slot-target` with slot id `design.editor.inspector`
+3. `install-extension` so it appears inline in the inspector
+
+If creating the extension opens the standalone extension editor, return to
+the same design with `navigate` and `inspectorTab: "extensions"` after
+installing it.
+
+## Context shape
+
+Extensions installed in this slot receive `window.slotContext` with the
+current design id, active screen, selected element, zoom, mode, tool, and
+tweak values.
+
+## AI-driven style/artboard changes
+
+For AI-driven style/artboard changes triggered from the extension UI,
+extension HTML should call `agentNative.chat.send(...)` with the selected
+element's selector/sourceId and the request. On the agent side:
+
+1. Call `view-screen` first.
+2. Prefer `apply-visual-edit` for element style/class/text changes.
+3. Use `update-design` or `generate-design` with `canvasFrames` for overview
+   artboard placement changes.

package/corpus/templates/design/.agents/skills/responsive-breakpoints/SKILL.md

@@ -35,7 +35,10 @@ scopes to `≤ 809px`). `breakpointUpperBoundPx` in
 - `set-active-breakpoint` — persists the active edit scope to application
   state (`design-active-breakpoint:<designId>`); the UI mirrors it in the
   `design-selection` state (`activeBreakpointId`). Check the active
-  breakpoint via `view-screen` before making responsive-only edits.
+  breakpoint via `view-screen` before making responsive-only edits. Its
+  `editScope` is `cascade-smaller` by default (edits at this breakpoint also
+  apply to every narrower one); pass `only` when the user explicitly wants a
+  bounded, breakpoint-only override.
 
 The UI's breakpoint bar (chips above the focused screen) and the overview's
 side-by-side linked frames drive the same state — a chip click changes the

package/corpus/templates/design/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

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

@@ -16,6 +16,15 @@ 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.
 
+## Installing this skill for an external MCP host
+
+The hosted install path
+(`npx @agent-native/core@latest skills add visual-edit`, or `design` for the
+full Design bundle) installs the exported instructions and registers the
+hosted Design MCP connector together. The open Skills CLI path
+(`npx skills@latest add BuilderIO/agent-native --skill visual-edit`) installs
+exported instructions only, with no MCP connector registration.
+
 ## Core Model
 
 - Each screen is a URL-backed iframe, not copied HTML.
@@ -227,6 +236,14 @@ the connected app's text/code files through the bridge
   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.
+- If the agent calls `write-local-file` directly (not through a UI save) and it
+  fails with "no write-consent grant", call `request-localhost-write-consent`.
+  It opens the write-consent dialog in the editor, or reports `alreadyGranted`
+  if one already exists. Granting is human-only —
+  `grant-localhost-write-consent` is hidden from agents, so you cannot approve
+  it yourself. Tell the user to click "Allow writes", then retry
+  `write-local-file` once. Do not keep retrying blindly: the write stays
+  blocked until the user approves.
 - 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.