@agent-native/core 0.122.4 → 0.123.0

package/src/agent/types.ts

@@ -388,11 +388,15 @@ export type ContinuationReason = (typeof CONTINUATION_REASONS)[number];
 
 /**
  * True when an `agent_runs.terminal_reason` marks a CHUNK boundary rather than
- * the end of the turn. Both writers (`terminalReasonForRun` in run-manager and
- * `markBackgroundContinuationChunkTerminal` in production-agent) record
- * status='completed' with one of these while a chained successor run carries the
- * turn on, so such a row must never be reported to a client as a plain `done`.
- * Mirrored client-side by `BACKGROUND_CONTINUATION_TERMINAL_REASONS`.
+ * the end of the turn — i.e. the run was TRUNCATED at a budget/timeout/loop/
+ * no-progress boundary and did not finish what it was asked to do.
+ *
+ * This is the single predicate for "the reason says this run did not finish".
+ * `setRunTerminalReason` (run-store) uses it to record `status='truncated'`
+ * instead of `'completed'`, so consumers should read the status rather than
+ * re-deriving truncation from the reason. It stays exported for legacy
+ * `status='completed'` rows written before the `truncated` status existed,
+ * which linger for one retention window.
  */
 export function isContinuationTerminalReason(reason: unknown): boolean {
   return (
@@ -406,4 +410,17 @@ export interface RunEvent {
   event: AgentChatEvent;
 }
 
-export type RunStatus = "running" | "completed" | "errored" | "aborted";
+/**
+ * `agent_runs.status`. `completed` means the turn actually finished (terminal
+ * reason `done`); `truncated` means it stopped at a budget/timeout/loop/
+ * no-progress boundary with work still outstanding. Truncations were previously
+ * filed as `completed`, which made them invisible to every success-rate query
+ * and — because retention keys off status — deleted them a week before the
+ * genuine failures they belong with.
+ */
+export type RunStatus =
+  | "running"
+  | "completed"
+  | "truncated"
+  | "errored"
+  | "aborted";

package/src/application-state/script-helpers.ts

@@ -12,7 +12,10 @@
  * context) should fall through to the env var.
  */
 
-import { getRequestRunContext } from "../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestRunContext,
+} from "../server/request-context.js";
 import {
   appStateGet,
   appStatePut,
@@ -42,7 +45,7 @@ async function resolveSessionId(): Promise<string> {
     // request-context not available — fall through to env var
   }
 
-  const email = process.env.AGENT_USER_EMAIL;
+  const email = getAmbientUserEmail();
   if (email) return email;
 
   throw new Error(

package/src/cli/agents.ts

@@ -1,8 +1,17 @@
-import { discoverAgents } from "../server/agent-discovery.js";
+import {
+  formatCapabilityDetail,
+  formatCapabilitySummary,
+  loadAllCapabilities,
+  loadCapabilities,
+  MAX_APPS,
+} from "../server/agent-capabilities.js";
+import { discoverAgents, findAgent } from "../server/agent-discovery.js";
 
 export interface ParsedAgentsArgs {
   command: "list" | "help";
   selfAppId?: string;
+  app?: string;
+  capabilities: boolean;
   json: boolean;
   errors: string[];
 }
@@ -15,6 +24,7 @@ export interface AgentsCliIo {
 export function parseAgentsArgs(args: string[]): ParsedAgentsArgs {
   const parsed: ParsedAgentsArgs = {
     command: "list",
+    capabilities: false,
     json: false,
     errors: [],
   };
@@ -39,6 +49,24 @@ export function parseAgentsArgs(args: string[]): ParsedAgentsArgs {
       parsed.json = true;
       continue;
     }
+    if (name === "capabilities" || name === "what-can-they-do") {
+      parsed.capabilities = true;
+      continue;
+    }
+    if (name === "app") {
+      const value =
+        inlineValue ??
+        (args[i + 1] !== undefined && !args[i + 1].startsWith("--")
+          ? args[++i]
+          : undefined);
+      if (!value) {
+        parsed.errors.push(`Missing value for --${name}`);
+      } else {
+        parsed.app = value;
+        parsed.capabilities = true;
+      }
+      continue;
+    }
     if (name === "self" || name === "self-app-id") {
       const value =
         inlineValue ??
@@ -82,7 +110,47 @@ export async function runAgents(
     return 1;
   }
 
+  if (parsed.app) {
+    const agent = await findAgent(parsed.app, parsed.selfAppId);
+    if (!agent) {
+      const available = (await discoverAgents(parsed.selfAppId))
+        .map((peer) => peer.id)
+        .join(", ");
+      stderr(
+        `No connected agent "${parsed.app}". Available: ${available || "(none)"}`,
+      );
+      return 1;
+    }
+    const peer = await loadCapabilities(agent);
+    stdout(
+      parsed.json
+        ? JSON.stringify(toCapabilityJson(peer), null, 2)
+        : formatCapabilityDetail(peer, callHint),
+    );
+    return 0;
+  }
+
   const agents = await discoverAgents(parsed.selfAppId);
+
+  if (parsed.capabilities) {
+    if (agents.length === 0) {
+      stdout("No connected agents found.");
+      return 0;
+    }
+    const shown = agents.slice(0, MAX_APPS);
+    const peers = await loadAllCapabilities(shown);
+    stdout(
+      parsed.json
+        ? JSON.stringify({ agents: peers.map(toCapabilityJson) }, null, 2)
+        : formatCapabilitySummary(
+            peers,
+            agents.length - shown.length,
+            (appId) => `run agent-native agents list --app ${appId}`,
+          ),
+    );
+    return 0;
+  }
+
   if (parsed.json) {
     stdout(JSON.stringify({ agents }, null, 2));
     return 0;

package/src/cli/app-skill.ts

@@ -681,7 +681,7 @@ export function exportedSkillContentHash(
     `mcp:${mcpServerNames(manifest).join(",")}:${manifest.hosted.mcpUrl}`,
   );
   return createHash("sha256")
-    .update(parts.join("\n\n"))
+    .update(parts.join("\n\u0000\n"))
     .digest("hex")
     .slice(0, 12);
 }

package/src/cli/code-agent-executor.ts

@@ -50,7 +50,11 @@ import {
   readAgentsBundleFromFs,
   generateDevelopmentSkillsPromptBlock,
 } from "../server/agents-bundle.js";
-import { runWithRequestContext } from "../server/request-context.js";
+import {
+  getAmbientOrgId,
+  getAmbientUserEmail,
+  runWithRequestContext,
+} from "../server/request-context.js";
 import {
   isReasoningEffort,
   type ReasoningEffort,
@@ -1157,8 +1161,8 @@ function runWithOptionalCodeAgentRequestContext<T>(
   const userEmail =
     metadataString(run, "ownerEmail") ??
     metadataString(run, "userEmail") ??
-    process.env.AGENT_USER_EMAIL;
-  const orgId = metadataString(run, "orgId") ?? process.env.AGENT_ORG_ID;
+    getAmbientUserEmail();
+  const orgId = metadataString(run, "orgId") ?? getAmbientOrgId();
   if (!userEmail && !orgId) return fn();
   return runWithRequestContext({ userEmail, orgId }, fn);
 }

package/src/cli/design-connect.ts

@@ -1108,6 +1108,27 @@ function resolvePreviewSnapshotUrl(
   return parsed.toString();
 }
 
+/**
+ * Remove a literal `previewToken` query pair via raw string splitting instead
+ * of `URLSearchParams`. `URLSearchParams` re-serializes the ENTIRE query
+ * string on mutation, turning a valueless pair like `?url` into `?url=` even
+ * when `previewToken` was never present — which silently changes which
+ * codepath Vite's dev server routes the request to (e.g. `?url` vs `?url=`
+ * resolve to different response bodies). Returns `search` untouched whenever
+ * `previewToken` is absent, so every other proxied query string reaches the
+ * dev server byte-for-byte.
+ */
+function stripPreviewTokenQueryParam(search: string): string {
+  if (!search.includes("previewToken")) return search;
+  const raw = search.startsWith("?") ? search.slice(1) : search;
+  const kept = raw
+    .split("&")
+    .filter(
+      (pair) => pair !== "previewToken" && !pair.startsWith("previewToken="),
+    );
+  return kept.length > 0 ? `?${kept.join("&")}` : "";
+}
+
 function resolvePreviewProxyUrl(
   devServerUrl: string,
   requestUrl: string | undefined,
@@ -2227,7 +2248,23 @@ export async function startDesignConnectBridge(
 
       // ── Read-only preview routes (preview token required) ────────────────
 
-      if (pathname === "/" || pathname === "/manifest.json") {
+      // The injected <base href> re-points the proxied app's own
+      // <link rel="manifest" href="/manifest.json"> at the bridge, which
+      // would otherwise collide with the bridge's own control-plane manifest
+      // below. Browsers tag that fetch with Sec-Fetch-Dest: manifest (a
+      // request-metadata header Node's fetch never sends), so existing
+      // control-plane callers — the Design app and `fetchRunningBridgeManifest`
+      // (used by `design connect --json` / daemon self-detection) — keep
+      // hitting the bridge manifest unchanged, while the app's own manifest
+      // request falls through to the ordinary authenticated proxy below.
+      const isProxiedAppManifestRequest =
+        (req.method === "GET" || req.method === "HEAD") &&
+        pathname === "/manifest.json" &&
+        readHeader(req, "sec-fetch-dest") === "manifest";
+      if (
+        !isProxiedAppManifestRequest &&
+        (pathname === "/" || pathname === "/manifest.json")
+      ) {
         if (rejectInvalidPreviewToken()) return;
         sendJson(res, 200, manifest as unknown as Record<string, unknown>);
         return;
@@ -2676,7 +2713,13 @@ export async function startDesignConnectBridge(
         req.method &&
         ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(req.method)
       ) {
-        if (!previewTokenValid) {
+        // The browser's own manifest-link fetch algorithm omits credentials
+        // and custom headers by spec default, so it structurally cannot carry
+        // a previewToken. That is consistent with the proxied dev server,
+        // which already serves this exact path with no auth of its own — so
+        // this narrow, unspoofable (Sec-Fetch-Dest is a forbidden header,
+        // unsettable from page JS) case is exempted from the token gate.
+        if (!previewTokenValid && !isProxiedAppManifestRequest) {
           sendJson(res, 401, {
             ok: false,
             error: "invalid or missing preview token",
@@ -2686,10 +2729,9 @@ export async function startDesignConnectBridge(
         void (async () => {
           try {
             const proxyRequestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
-            proxyRequestUrl.searchParams.delete("previewToken");
             const targetUrl = resolvePreviewProxyUrl(
               manifest.devServerUrl,
-              `${proxyRequestUrl.pathname}${proxyRequestUrl.search}`,
+              `${proxyRequestUrl.pathname}${stripPreviewTokenQueryParam(proxyRequestUrl.search)}`,
             );
             const method = req.method ?? "GET";
             const requestBody =
@@ -2775,13 +2817,12 @@ export async function startDesignConnectBridge(
       );
       return;
     }
-    requestUrl.searchParams.delete("previewToken");
     let targetUrl: URL;
     try {
       targetUrl = new URL(
         resolvePreviewProxyUrl(
           manifest.devServerUrl,
-          `${requestUrl.pathname}${requestUrl.search}`,
+          `${requestUrl.pathname}${stripPreviewTokenQueryParam(requestUrl.search)}`,
         ),
       );
     } catch {
@@ -3088,27 +3129,60 @@ async function startDetachedDesignBridge(
   }
 
   const invocation = resolveCurrentCliInvocation(argv);
+  // A detached bridge that dies — port already taken, crash on boot, killed
+  // with its process group — used to do so with stdio "ignore", so the failure
+  // left no trace anywhere and Design silently fell back to non-editable
+  // iframes. Keep its output on disk so the death is diagnosable.
+  const logPath = await createDaemonLogPath(manifest.rootPath);
+  const logFd = await fs.open(logPath, "a");
   const child = spawn(invocation.command, invocation.args, {
     cwd: process.cwd(),
     detached: true,
     env: process.env,
-    stdio: "ignore",
+    stdio: ["ignore", logFd.fd, logFd.fd],
     shell: process.platform === "win32",
   });
   child.unref();
 
   if (await waitForBridgeHealth(manifest.bridgeUrl)) {
+    await logFd.close();
     console.error(`Design localhost bridge running at ${manifest.bridgeUrl}`);
+    console.error(`Bridge log: ${logPath}`);
     console.log(JSON.stringify(manifest, null, 2));
     return 0;
   }
 
+  const tail = await readDaemonLogTail(logPath);
+  await logFd.close();
   console.error(
-    `Timed out waiting for detached Design bridge at ${manifest.bridgeUrl}`,
+    [
+      `Timed out waiting for detached Design bridge at ${manifest.bridgeUrl}`,
+      `Bridge log: ${logPath}`,
+      tail ? `Last output:\n${tail}` : "The bridge produced no output.",
+    ].join("\n"),
   );
   return 1;
 }
 
+async function createDaemonLogPath(rootPath: string): Promise<string> {
+  const dir = path.join(rootPath, ".agent-native");
+  await fs.mkdir(dir, { recursive: true });
+  return path.join(dir, "design-connect.log");
+}
+
+async function readDaemonLogTail(
+  logPath: string,
+  maxBytes = 4000,
+): Promise<string> {
+  try {
+    const contents = await fs.readFile(logPath, "utf8");
+    return contents.slice(-maxBytes).trim();
+  } catch {
+    // An unreadable log must not mask the timeout the caller is reporting.
+    return "";
+  }
+}
+
 export async function runDesign(argv: string[]) {
   const subcommand = argv[0];
   if (subcommand !== "connect") {

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

@@ -16,11 +16,33 @@ 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.
 - 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
+  static DOM snapshot.
+- The live editor is same-origin through the local bridge proxy. This boots
+  CSR apps and root-relative assets, but it is still a localhost editing proxy:
+  app-origin cookies, WebSockets/HMR, SSE, and non-GET app API calls may need a
+  future dev-server/plugin integration for perfect parity with the app's own
+  origin.
+- Interact mode renders the app's normal URL so app navigation, scrolling,
+  links, and form controls behave as they would in the browser.
+- 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. 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
@@ -32,6 +54,28 @@ iframe-backed screens on the infinite canvas.
   \`localhost:1234/onboarding/1\` means
   \`http://localhost:1234/onboarding/1\`.
 
+## Select And Reprompt
+
+When a chat message begins with \`[Reprompt selection]\`, the selected subtree is
+a hard write boundary. The only mutation path is \`propose-node-rewrite\` with
+the exact \`repromptId\`, target, and \`baseVersionHash\` captured in
+\`design-reprompt-pending:<designId>:<fileId>\`. Never use \`apply-visual-edit\`,
+\`apply-source-edit\`, \`write-source\`, \`write-local-file\`, \`edit-design\`, or any
+other content-writing action for that request. Clarifying questions are allowed,
+but a requested change must remain a proposal.
+
+Produce one variant by default. Produce two or three only when the instruction
+asks for options. A retry includes \`priorProposalId\`; keep the same target and
+base version, incorporate the feedback, and call \`propose-node-rewrite\` again.
+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
+\`view-screen\`, read the active \`design.reprompt.proposal\`, and pass its
+\`proposalId\` plus the zero-based \`variantIndex\` to \`resolve-node-rewrite\`.
+
 ## Review Quality
 
 - Treat the running app as the truth. Preserve its component language, tokens,
@@ -81,6 +125,14 @@ 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.
@@ -100,13 +152,22 @@ the command exits.
 For a manual health/manifest check on the running bridge:
 
 \`\`\`bash
-curl http://127.0.0.1:7331/manifest.json
+curl http://127.0.0.1:7331/health
 \`\`\`
 
+\`/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.
 
+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
 
 Prefer the single authenticated \`open-visual-edit\` action. It registers or
@@ -139,34 +200,64 @@ 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:
+### Desktop and mobile side by side
+
+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 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"]
+}'
+\`\`\`
+
+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 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" }
-  ]
+  "devServerUrl": "http://localhost:5173",
+  "paths": ["/settings", "/team"],
+  "startY": 2200
 }'
 \`\`\`
 
-For responsive follow-ups, call \`open-visual-edit\` again with the same
-\`designId\` and \`connectionId\`, plus explicit viewport dimensions:
+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 open-visual-edit '{
   "designId": "<existing-design-id>",
   "connectionId": "<existing-connection-id>",
-  "devServerUrl": "http://localhost:5173",
-  "paths": ["/"],
-  "defaultWidth": 390,
-  "defaultHeight": 844,
-  "startX": 1600,
-  "startY": 0
+  "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" }
+  ]
 }'
 \`\`\`
 
@@ -194,26 +285,77 @@ Fallback, only when \`open-visual-edit\` is unavailable:
   \`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.
+- 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
 
 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
+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
+
+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.
+Treat that root like VS Code opened at the connected project directory: file
+tree, search, open/edit, and save are backed by the real local 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.
+- 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.
+
 ## 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\`.
 - 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.
+  \`.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
@@ -223,6 +365,9 @@ path/query or duplicate the screen and update the copy's URL metadata.
 
 - \`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.
 `;