diff --git a/packages/agent/src/adapters/local-tools/index.ts b/packages/agent/src/adapters/local-tools/index.ts
index c2aab7139d..716bbb478e 100644
--- a/packages/agent/src/adapters/local-tools/index.ts
+++ b/packages/agent/src/adapters/local-tools/index.ts
@@ -1,4 +1,5 @@
 import type { LocalTool, LocalToolCtx, LocalToolGateMeta } from "./registry";
+import { canvasCheckoutTool, canvasPublishTool } from "./tools/canvas";
 import { cloneRepoTool } from "./tools/clone-repo";
 import { listReposTool } from "./tools/list-repos";
 import { signedCommitTool } from "./tools/signed-commit";
@@ -23,6 +24,8 @@ export const LOCAL_TOOLS: LocalTool[] = [
   listReposTool,
   cloneRepoTool,
   speakTool,
+  canvasCheckoutTool,
+  canvasPublishTool,
 ];
 
 /** Tools whose gate passes for the given context — the set to actually expose. */
diff --git a/packages/agent/src/adapters/local-tools/tools/canvas.test.ts b/packages/agent/src/adapters/local-tools/tools/canvas.test.ts
new file mode 100644
index 0000000000..7cf32f9e2c
--- /dev/null
+++ b/packages/agent/src/adapters/local-tools/tools/canvas.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { canvasScratchDir, canvasScratchFile } from "./canvas";
+
+// Version composition and the stale-base rejection live server-side in the
+// desktop-fs canvas action (and are tested there); the tool's own logic is
+// the scratch-file plumbing.
+describe("canvas scratch paths", () => {
+  it("keys the scratch dir and file by canvas id, outside any workspace", () => {
+    expect(canvasScratchDir("dash-1")).toBe("/tmp/posthog-canvas/dash-1");
+    expect(canvasScratchFile("dash-1")).toBe(
+      "/tmp/posthog-canvas/dash-1/canvas.tsx",
+    );
+  });
+});
diff --git a/packages/agent/src/adapters/local-tools/tools/canvas.ts b/packages/agent/src/adapters/local-tools/tools/canvas.ts
new file mode 100644
index 0000000000..d846678dfd
--- /dev/null
+++ b/packages/agent/src/adapters/local-tools/tools/canvas.ts
@@ -0,0 +1,232 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import {
+  DesktopCanvasVersionConflictError,
+  PostHogAPIClient,
+} from "../../../posthog-api";
+import { resolveSandboxPosthogApi } from "../../../signed-commit-artefacts";
+import { defineLocalTool, type LocalToolResult } from "../registry";
+
+/**
+ * Local tools for working on freeform canvases (desktop-fs `dashboard` rows)
+ * as scratch files, so the agent edits the source incrementally with its
+ * native file tools instead of regenerating (or transcribing) the whole file:
+ *
+ * - `canvas_checkout` fetches the canvas, writes `meta.code` to a
+ *   deterministic scratch path tool-side (no model transcription), and stashes
+ *   the fetched `currentVersionId` as the publish-time concurrency base.
+ * - `canvas_publish` reads the scratch file from disk (again, no
+ *   transcription) and publishes through the desktop-fs canvas action, which
+ *   owns version composition server-side. The stashed base rides along as
+ *   `expected_current_version_id`, so a publish based on a stale read (a
+ *   concurrent edit, or a user's undo) is rejected atomically with a version
+ *   conflict instead of clobbering the newer head.
+ *
+ * Credentials come from the sandbox environment (see
+ * `resolveSandboxPosthogApi`), so this works identically from the Claude
+ * in-process server and the Codex stdio child.
+ */
+
+// Deliberately outside any workspace: scratch files never show up in
+// changed-file diff panels or `git status` (a canvas task can lazily attach a
+// repo), and the canvas id keeps concurrent generations from colliding.
+export const CANVAS_SCRATCH_ROOT = "/tmp/posthog-canvas";
+
+export function canvasScratchDir(canvasId: string): string {
+  return path.join(CANVAS_SCRATCH_ROOT, canvasId);
+}
+
+export function canvasScratchFile(canvasId: string): string {
+  return path.join(canvasScratchDir(canvasId), "canvas.tsx");
+}
+
+function baseVersionMarkerFile(canvasId: string): string {
+  return path.join(canvasScratchDir(canvasId), ".base-version.json");
+}
+
+interface CanvasMeta {
+  code?: string;
+  currentVersionId?: string;
+  [key: string]: unknown;
+}
+
+interface CanvasFsEntry {
+  id: string;
+  path: string;
+  type?: string;
+  meta?: CanvasMeta | null;
+}
+
+interface BaseVersionMarker {
+  versionId?: string;
+  fetchedAt: number;
+}
+
+function createClient(): PostHogAPIClient | undefined {
+  const api = resolveSandboxPosthogApi();
+  if (!api) return undefined;
+  return new PostHogAPIClient({
+    apiUrl: api.apiUrl,
+    projectId: api.projectId,
+    getApiKey: () => api.apiKey,
+  });
+}
+
+async function fetchCanvasEntry(canvasId: string): Promise<CanvasFsEntry> {
+  const client = createClient();
+  if (!client) {
+    throw new Error("No PostHog credentials available in this session.");
+  }
+  const entry = await client.getDesktopFsEntry<CanvasFsEntry>(canvasId);
+  if (!entry) {
+    throw new Error(
+      `Canvas ${canvasId} not found. Check the id — it should be a desktop-fs dashboard row id.`,
+    );
+  }
+  if (entry.type !== "dashboard") {
+    throw new Error(
+      `Entry ${canvasId} is type "${entry.type}", not a canvas ("dashboard").`,
+    );
+  }
+  return entry;
+}
+
+function readMarker(canvasId: string): BaseVersionMarker | undefined {
+  try {
+    return JSON.parse(
+      readFileSync(baseVersionMarkerFile(canvasId), "utf8"),
+    ) as BaseVersionMarker;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeMarker(canvasId: string, marker: BaseVersionMarker): void {
+  mkdirSync(canvasScratchDir(canvasId), { recursive: true });
+  writeFileSync(baseVersionMarkerFile(canvasId), JSON.stringify(marker));
+}
+
+function errorResult(text: string): LocalToolResult {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+const CONFLICT_MESSAGE = (canvasId: string) =>
+  `version-conflict: the canvas changed since your checkout (a concurrent edit, or the user's undo). ` +
+  `Recover: call canvas_checkout with id "${canvasId}" again (it re-seeds the scratch file from the live source), ` +
+  `re-apply your edits to it, then call canvas_publish again.`;
+
+export const canvasCheckoutTool = defineLocalTool({
+  name: "canvas_checkout",
+  description:
+    "Check out a PostHog canvas (a freeform React desktop-fs dashboard) for editing: fetches the live " +
+    "source, writes it to a local scratch file, and records the version your edits are based on. " +
+    "Returns the file path. Edit that file with your normal file-editing tools, then call " +
+    "canvas_publish to save. Always start canvas work with this tool.",
+  schema: {
+    id: z.string().describe("The canvas (desktop-fs dashboard row) id."),
+  },
+  alwaysLoad: true,
+  isEnabled: () => resolveSandboxPosthogApi() !== undefined,
+  handler: async (_ctx, args): Promise<LocalToolResult> => {
+    try {
+      const entry = await fetchCanvasEntry(args.id);
+      const file = canvasScratchFile(args.id);
+      const code = entry.meta?.code ?? "";
+      mkdirSync(canvasScratchDir(args.id), { recursive: true });
+      writeFileSync(file, code);
+      writeMarker(args.id, {
+        versionId: entry.meta?.currentVersionId,
+        fetchedAt: Date.now(),
+      });
+      const lines = code ? code.split("\n").length : 0;
+      const text = code
+        ? `Checked out canvas "${entry.path}" to ${file} (${lines} lines, base version ${
+            entry.meta?.currentVersionId ?? "none"
+          }).\nApply your changes by editing that file, then call canvas_publish with id "${args.id}".`
+        : `Canvas "${entry.path}" is empty. Author the complete single-file React app at ${file}, then call canvas_publish with id "${args.id}".`;
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return errorResult(
+        `canvas_checkout failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  },
+});
+
+export const canvasPublishTool = defineLocalTool({
+  name: "canvas_publish",
+  description:
+    "Publish the checked-out canvas: reads the scratch file written by canvas_checkout and saves it as " +
+    "the canvas's new live version, guarded against the canvas having changed since checkout. Call " +
+    "exactly once when the edit is complete. On a version-conflict error, re-run canvas_checkout, " +
+    "re-apply your edits, and publish again.",
+  schema: {
+    id: z.string().describe("The canvas (desktop-fs dashboard row) id."),
+    prompt: z
+      .string()
+      .optional()
+      .describe(
+        "One short sentence describing the change, stored on the version history entry.",
+      ),
+  },
+  alwaysLoad: true,
+  isEnabled: () => resolveSandboxPosthogApi() !== undefined,
+  handler: async (_ctx, args): Promise<LocalToolResult> => {
+    let code: string;
+    try {
+      code = readFileSync(canvasScratchFile(args.id), "utf8");
+    } catch {
+      return errorResult(
+        `canvas_publish failed: no scratch file for canvas "${args.id}". Call canvas_checkout first, edit the file it returns, then publish.`,
+      );
+    }
+    if (!code.trim()) {
+      return errorResult(
+        `canvas_publish failed: the scratch file for canvas "${args.id}" is empty.`,
+      );
+    }
+    const marker = readMarker(args.id);
+    if (!marker) {
+      return errorResult(
+        `canvas_publish failed: no checkout record for canvas "${args.id}". Call canvas_checkout first.`,
+      );
+    }
+    const client = createClient();
+    if (!client) {
+      return errorResult(
+        "canvas_publish failed: no PostHog credentials available in this session.",
+      );
+    }
+    try {
+      const entry = await client.publishDesktopCanvas<CanvasFsEntry>(args.id, {
+        code,
+        prompt: args.prompt,
+        expectedCurrentVersionId: marker.versionId ?? null,
+      });
+      // Advance the base so a follow-up publish in the same session works
+      // without a re-checkout.
+      const newVersionId = entry.meta?.currentVersionId;
+      writeMarker(args.id, { versionId: newVersionId, fetchedAt: Date.now() });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Published canvas "${args.id}"${
+              newVersionId ? ` (new version ${newVersionId})` : ""
+            }. The canvas is live; do not paste the code into chat.`,
+          },
+        ],
+      };
+    } catch (err) {
+      if (err instanceof DesktopCanvasVersionConflictError) {
+        return errorResult(
+          `canvas_publish failed: ${CONFLICT_MESSAGE(args.id)}`,
+        );
+      }
+      return errorResult(
+        `canvas_publish failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  },
+});
diff --git a/packages/agent/src/posthog-api.ts b/packages/agent/src/posthog-api.ts
index b3596fe424..9d5f425a66 100644
--- a/packages/agent/src/posthog-api.ts
+++ b/packages/agent/src/posthog-api.ts
@@ -63,6 +63,14 @@ export type TaskRunUpdate = Partial<
   state_remove_keys?: string[];
 };
 
+/** A guarded canvas publish was based on a stale version (409 from the API). */
+export class DesktopCanvasVersionConflictError extends Error {
+  constructor(readonly currentVersionId: string | null) {
+    super("Canvas version conflict: the canvas changed since it was read.");
+    this.name = "DesktopCanvasVersionConflictError";
+  }
+}
+
 export class PostHogAPIClient {
   private config: PostHogAPIConfig;
 
@@ -338,6 +346,71 @@ export class PostHogAPIClient {
       .filter((artifact): artifact is TaskRunArtifact => !!artifact);
   }
 
+  /**
+   * Fetch a desktop file system entry (e.g. a canvas "dashboard" row) by id.
+   * Returns null on 404 so callers can produce a friendly not-found message.
+   */
+  async getDesktopFsEntry<T>(entryId: string): Promise<T | null> {
+    const teamId = this.getTeamId();
+    const response = await this.performRequestWithRetry(
+      `/api/projects/${teamId}/desktop_file_system/${encodeURIComponent(entryId)}/`,
+    );
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to fetch desktop-fs entry (${response.status})`);
+    }
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Publish a freeform canvas's source via the desktop-fs canvas action. The
+   * server owns version composition (appends the full-file snapshot, moves
+   * `currentVersionId`, truncates any redo tail) and rejects a publish whose
+   * `expectedCurrentVersionId` no longer matches the live head with a 409 —
+   * surfaced as DesktopCanvasVersionConflictError. Backends predating the
+   * guard ignore the field and publish unguarded, so this degrades gracefully.
+   */
+  async publishDesktopCanvas<T>(
+    entryId: string,
+    input: {
+      code: string;
+      prompt?: string;
+      /** The head version the code was based on; null when it was empty. */
+      expectedCurrentVersionId: string | null;
+    },
+  ): Promise<T> {
+    const teamId = this.getTeamId();
+    const body: Record<string, unknown> = {
+      code: input.code,
+      expected_current_version_id: input.expectedCurrentVersionId,
+    };
+    if (input.prompt) {
+      body.prompt = input.prompt;
+    }
+    const response = await this.performRequestWithRetry(
+      `/api/projects/${teamId}/desktop_file_system/${encodeURIComponent(entryId)}/canvas/`,
+      { method: "PATCH", body: JSON.stringify(body) },
+    );
+    if (response.status === 409) {
+      let currentVersionId: string | null = null;
+      try {
+        const parsed = (await response.json()) as {
+          current_version_id?: string | null;
+        };
+        currentVersionId = parsed.current_version_id ?? null;
+      } catch {
+        // Conflict body unavailable — the status alone carries the signal.
+      }
+      throw new DesktopCanvasVersionConflictError(currentVersionId);
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to publish canvas (${response.status})`);
+    }
+    return response.json() as Promise<T>;
+  }
+
   /** Signal reports the given task is associated with (via report task associations). */
   async getSignalReportIdsForTask(taskId: string): Promise<string[]> {
     const teamId = this.getTeamId();
diff --git a/packages/core/src/canvas/canvasTemplates.ts b/packages/core/src/canvas/canvasTemplates.ts
index d75cfba72b..7eb864c803 100644
--- a/packages/core/src/canvas/canvasTemplates.ts
+++ b/packages/core/src/canvas/canvasTemplates.ts
@@ -28,10 +28,9 @@ const FREEFORM_WHITELIST_NAMES = FREEFORM_WHITELIST.map((e) => e.name).join(
 const FREEFORM_BASE = [
   "You are PostHog Canvas, an agent that builds a freeform React app for the user's current PostHog project. The app runs in a sandboxed iframe.",
   "",
-  "OUTPUT FORMAT — every turn:",
-  "- Write a SHORT sentence of prose, then the COMPLETE app as ONE fenced code block tagged tsx (```tsx ... ```).",
-  "- FULL-FILE REWRITE: always output the entire file, even for a tiny change. Never output a partial file, a diff, or multiple code blocks.",
+  "OUTPUT FORMAT — the app is ONE complete file:",
   "- The file MUST `export default` a single React component that takes no props.",
+  "- Maintain it as a working file with your file-editing tools: seed it once, then apply changes as TARGETED edits. Do not regenerate the whole file for a small change, and do not paste the source into chat — a short sentence describing the change is enough.",
   "",
   "IMPORTS — allowed packages ONLY:",
   `- You may import ONLY from: ${FREEFORM_WHITELIST_NAMES}.`,
diff --git a/packages/core/src/canvas/freeformSchemas.ts b/packages/core/src/canvas/freeformSchemas.ts
index 8f683bfa33..be44d942d9 100644
--- a/packages/core/src/canvas/freeformSchemas.ts
+++ b/packages/core/src/canvas/freeformSchemas.ts
@@ -5,7 +5,8 @@ import { z } from "zod";
 export const FREEFORM_TEMPLATE_ID = "freeform";
 
 // A single point in a freeform canvas's edit history. Every agent turn appends
-// one full-file snapshot (Q7: full-file rewrite); the user can revert to any of
+// one full-file snapshot (the agent edits a local scratch copy incrementally,
+// then publishes the finished file wholesale); the user can revert to any of
 // them and the `currentVersionId` pointer is what publishes. We keep whole-file
 // snapshots rather than diffs because canvases are small and a snapshot can
 // never fail to reconstruct.
@@ -163,6 +164,51 @@ export type CanvasAnalyticsConfig = z.infer<typeof canvasAnalyticsConfigSchema>;
 export const canvasThemeSchema = z.enum(["light", "dark"]);
 export type CanvasTheme = z.infer<typeof canvasThemeSchema>;
 
+// ---------------------------------------------------------------------------
+// Annotation targets captured by the comment-mode overlay (structured canvas
+// feedback). Deliberately LLM-locatable rather than machine-precise: the
+// consumer is the generation agent locating the spot in source IT wrote, so
+// the bounded text + stable attributes matter more than selector exactness.
+// ---------------------------------------------------------------------------
+export const canvasElementTargetSchema = z.object({
+  type: z.literal("element"),
+  // Best-effort CSS selector for the rendered element (stable attributes
+  // preferred, nth-of-type fallback).
+  selector: z.string(),
+  tag: z.string(),
+  // Bounded innerText snippet — usually the strongest locator.
+  text: z.string(),
+  ariaLabel: z.string().nullable().optional(),
+  // The stable attributes present on the element (data-attr, id, role, …).
+  attributes: z.record(z.string(), z.string()),
+});
+export type CanvasElementTarget = z.infer<typeof canvasElementTargetSchema>;
+
+export const canvasTextRangeTargetSchema = z.object({
+  type: z.literal("text-range"),
+  // The selected text, bounded.
+  text: z.string(),
+  ancestorSelector: z.string(),
+  ancestorTag: z.string(),
+});
+export type CanvasTextRangeTarget = z.infer<typeof canvasTextRangeTargetSchema>;
+
+export const canvasAnnotationTargetSchema = z.discriminatedUnion("type", [
+  canvasElementTargetSchema,
+  canvasTextRangeTargetSchema,
+]);
+export type CanvasAnnotationTarget = z.infer<
+  typeof canvasAnnotationTargetSchema
+>;
+
+// A queued annotation the host asks the overlay to render as a numbered pin.
+export const canvasAnnotationPinSchema = z.object({
+  id: z.string(),
+  n: z.number(),
+  selector: z.string(),
+});
+export type CanvasAnnotationPin = z.infer<typeof canvasAnnotationPinSchema>;
+
 // host -> iframe
 export const hostToCanvasMessageSchema = z.discriminatedUnion("type", [
   // First frame: hand the iframe its source + the run mode. The iframe does not
@@ -198,6 +244,19 @@ export const hostToCanvasMessageSchema = z.discriminatedUnion("type", [
     result: z.unknown().optional(),
     error: z.string().optional(),
   }),
+  // Toggle the annotation ("comment mode") overlay: crosshair cursor, hover
+  // highlight, and click-to-capture targets.
+  z.object({
+    channel: z.literal(CANVAS_CHANNEL),
+    type: z.literal("set-annotation-mode"),
+    enabled: z.boolean(),
+  }),
+  // The queued annotations to render as numbered pins over their targets.
+  z.object({
+    channel: z.literal(CANVAS_CHANNEL),
+    type: z.literal("annotation-pins"),
+    pins: z.array(canvasAnnotationPinSchema),
+  }),
 ]);
 export type HostToCanvasMessage = z.infer<typeof hostToCanvasMessageSchema>;
 
@@ -253,5 +312,12 @@ export const canvasToHostMessageSchema = z.discriminatedUnion("type", [
     type: z.literal("navigate"),
     nav: canvasNavIntentSchema,
   }),
+  // A comment-mode click captured an annotation target. The comment itself is
+  // typed host-side; only the target crosses the boundary.
+  z.object({
+    channel: z.literal(CANVAS_CHANNEL),
+    type: z.literal("annotation-target"),
+    target: canvasAnnotationTargetSchema,
+  }),
 ]);
 export type CanvasToHostMessage = z.infer<typeof canvasToHostMessageSchema>;
diff --git a/packages/ui/src/features/canvas/AGENTS.md b/packages/ui/src/features/canvas/AGENTS.md
index 0ea928dfbf..a21bc3a65a 100644
--- a/packages/ui/src/features/canvas/AGENTS.md
+++ b/packages/ui/src/features/canvas/AGENTS.md
@@ -75,10 +75,19 @@ The root `AGENTS.md` architecture rules still apply.
   documented as `DashboardFileMeta` in `dashboardSchemas.ts`. This keeps canvas
   and channel names in sync with the backend — the same surface that owns
   channels (top-level `folder` rows, see `hooks/useChannels.ts`).
-- `meta` is **last-write-wins, unversioned** at the fs layer (no `base_version`).
-  Freeform autosaves the whole file each agent turn, so a concurrent edit from
-  another client can clobber. Acceptable for now; revisit with optimistic
-  concurrency if multi-client editing becomes real.
+- `meta` is **last-write-wins, unversioned** at the fs layer (no `base_version`)
+  — except the **canvas publish action** (`PATCH …/:id/canvas/`), which owns
+  version composition server-side and accepts an optional
+  `expected_current_version_id`: a publish based on a stale version (a
+  concurrent edit or undo) is rejected 409 inside the row lock instead of
+  clobbering the newer head. The **agent publish path uses that guard**:
+  generation works the source as a local scratch file via the
+  `canvas_checkout` / `canvas_publish` local tools (`@posthog/agent`,
+  `adapters/local-tools/tools/canvas.ts`) — checkout records the fetched
+  `currentVersionId`, publish passes it as the expected version (backends
+  predating the field ignore it and publish unguarded). **User-side saves**
+  (`saveFreeform`) are still last-write-wins; adopt the same guard if
+  multi-client editing becomes real.
 
 ## Channel sidebar preloading
 
diff --git a/packages/ui/src/features/canvas/freeform/CanvasFrameHost.tsx b/packages/ui/src/features/canvas/freeform/CanvasFrameHost.tsx
index 56aaa920d9..45f6888cac 100644
--- a/packages/ui/src/features/canvas/freeform/CanvasFrameHost.tsx
+++ b/packages/ui/src/features/canvas/freeform/CanvasFrameHost.tsx
@@ -56,6 +56,9 @@ export function CanvasFrameHost() {
                 onError={slot.inputs.onError}
                 onRendered={slot.inputs.onRendered}
                 onNavigate={slot.inputs.onNavigate}
+                annotationMode={slot.inputs.annotationMode}
+                annotationPins={slot.inputs.annotationPins}
+                onAnnotationTarget={slot.inputs.onAnnotationTarget}
               />
             </ErrorBoundary>
           </div>
diff --git a/packages/ui/src/features/canvas/freeform/CanvasFramePlaceholder.tsx b/packages/ui/src/features/canvas/freeform/CanvasFramePlaceholder.tsx
index fb56f90e44..b442739bfb 100644
--- a/packages/ui/src/features/canvas/freeform/CanvasFramePlaceholder.tsx
+++ b/packages/ui/src/features/canvas/freeform/CanvasFramePlaceholder.tsx
@@ -1,5 +1,7 @@
 import type {
   CanvasAnalyticsConfig,
+  CanvasAnnotationPin,
+  CanvasAnnotationTarget,
   CanvasNavIntent,
 } from "@posthog/core/canvas/freeformSchemas";
 import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
@@ -19,6 +21,9 @@ export function CanvasFramePlaceholder({
   onError,
   onRendered,
   onNavigate,
+  annotationMode,
+  annotationPins,
+  onAnnotationTarget,
 }: {
   dashboardId: string;
   code: string;
@@ -27,6 +32,9 @@ export function CanvasFramePlaceholder({
   onError?: (message: string, stack?: string) => void;
   onRendered?: () => void;
   onNavigate?: (intent: CanvasNavIntent) => void;
+  annotationMode?: boolean;
+  annotationPins?: CanvasAnnotationPin[];
+  onAnnotationTarget?: (target: CanvasAnnotationTarget) => void;
 }) {
   const ref = useRef<HTMLDivElement>(null);
   const refreshKey = useCanvasRefreshNonce(`dashboard:${dashboardId}`);
@@ -45,6 +53,9 @@ export function CanvasFramePlaceholder({
       onError,
       onRendered,
       onNavigate,
+      annotationMode,
+      annotationPins,
+      onAnnotationTarget,
     }),
     [
       code,
@@ -54,6 +65,9 @@ export function CanvasFramePlaceholder({
       onError,
       onRendered,
       onNavigate,
+      annotationMode,
+      annotationPins,
+      onAnnotationTarget,
     ],
   );
 
diff --git a/packages/ui/src/features/canvas/freeform/FreeformCanvas.tsx b/packages/ui/src/features/canvas/freeform/FreeformCanvas.tsx
index 9a64218654..23578edb63 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformCanvas.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformCanvas.tsx
@@ -1,5 +1,7 @@
 import {
   type CanvasAnalyticsConfig,
+  type CanvasAnnotationPin,
+  type CanvasAnnotationTarget,
   type CanvasNavIntent,
   type CanvasToHostMessage,
   canvasToHostMessageSchema,
@@ -51,6 +53,12 @@ export interface FreeformCanvasProps {
    * reloads the frame via the existing reload path.
    */
   refreshKey?: number;
+  /** Comment mode: the overlay captures element/text targets on click. */
+  annotationMode?: boolean;
+  /** Queued annotations rendered as numbered pins over their targets. */
+  annotationPins?: CanvasAnnotationPin[];
+  /** Called when the overlay captures a target (the comment is typed host-side). */
+  onAnnotationTarget?: (target: CanvasAnnotationTarget) => void;
 }
 
 // Renders a freeform-React canvas inside a null-origin sandboxed iframe and
@@ -65,6 +73,9 @@ export function FreeformCanvas({
   onNavigate,
   analytics,
   refreshKey = 0,
+  annotationMode = false,
+  annotationPins,
+  onAnnotationTarget,
 }: FreeformCanvasProps) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
   // The canvas mirrors the host's light/dark theme. Passed via `init` (not the
@@ -92,25 +103,32 @@ export function FreeformCanvas({
     onError,
     onRendered,
     onNavigate,
+    onAnnotationTarget,
     code,
     mode,
     analytics,
     theme,
+    annotationMode,
+    annotationPins,
   });
   latest.current = {
     onDataRequest,
     onError,
     onRendered,
     onNavigate,
+    onAnnotationTarget,
     code,
     mode,
     analytics,
     theme,
+    annotationMode,
+    annotationPins,
   };
 
   const postInit = useCallback(() => {
     const p = latest.current;
-    iframeRef.current?.contentWindow?.postMessage(
+    const target = iframeRef.current?.contentWindow;
+    target?.postMessage(
       {
         channel: "posthog-canvas",
         type: "init",
@@ -121,6 +139,24 @@ export function FreeformCanvas({
       },
       "*",
     );
+    // A reload resets the overlay's state; re-sync comment mode + pins so they
+    // survive srcDoc changes exactly like the theme survives via init.
+    target?.postMessage(
+      {
+        channel: "posthog-canvas",
+        type: "set-annotation-mode",
+        enabled: p.annotationMode,
+      },
+      "*",
+    );
+    target?.postMessage(
+      {
+        channel: "posthog-canvas",
+        type: "annotation-pins",
+        pins: p.annotationPins ?? [],
+      },
+      "*",
+    );
   }, []);
 
   // The iframe reloads only when srcDoc changes (mode / analytics host); on
@@ -182,6 +218,9 @@ export function FreeformCanvas({
           // msg.nav is already allowlist-validated by safeParse below.
           latest.current.onNavigate?.(msg.nav);
           break;
+        case "annotation-target":
+          latest.current.onAnnotationTarget?.(msg.target);
+          break;
       }
     };
 
@@ -232,6 +271,30 @@ export function FreeformCanvas({
     );
   }, [theme]);
 
+  // Live comment-mode + pin updates (no remount; postInit re-syncs on reload).
+  useEffect(() => {
+    if (!readyRef.current) return;
+    iframeRef.current?.contentWindow?.postMessage(
+      {
+        channel: "posthog-canvas",
+        type: "set-annotation-mode",
+        enabled: annotationMode,
+      },
+      "*",
+    );
+  }, [annotationMode]);
+  useEffect(() => {
+    if (!readyRef.current) return;
+    iframeRef.current?.contentWindow?.postMessage(
+      {
+        channel: "posthog-canvas",
+        type: "annotation-pins",
+        pins: annotationPins ?? [],
+      },
+      "*",
+    );
+  }, [annotationPins]);
+
   return (
     <iframe
       ref={iframeRef}
diff --git a/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx b/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
index d59ac286a4..b81d5d149e 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
@@ -2,12 +2,16 @@ import {
   ArrowCounterClockwiseIcon,
   ArrowUUpLeftIcon,
   ArrowUUpRightIcon,
+  CursorClickIcon,
   ShapesIcon,
   SidebarSimpleIcon,
   SpinnerGapIcon,
   WarningIcon,
 } from "@phosphor-icons/react";
-import type { CanvasAnalyticsConfig } from "@posthog/core/canvas/freeformSchemas";
+import type {
+  CanvasAnalyticsConfig,
+  CanvasAnnotationTarget,
+} from "@posthog/core/canvas/freeformSchemas";
 import { useHostTRPC } from "@posthog/host-router/react";
 import {
   Button,
@@ -23,6 +27,10 @@ import {
   isCanvasGenerationRunning,
 } from "@posthog/ui/features/canvas/freeform/canvasGenerationStatus";
 import { useChannels } from "@posthog/ui/features/canvas/hooks/useChannels";
+import {
+  useCanvasAnnotations,
+  useCanvasAnnotationsStore,
+} from "@posthog/ui/features/canvas/stores/canvasAnnotationsStore";
 import { useCanvasChatPanelStore } from "@posthog/ui/features/canvas/stores/canvasChatPanelStore";
 import {
   useFreeformChatStore,
@@ -216,6 +224,32 @@ export function FreeformCanvasView({
   // Routes the canvas's allowlisted nav intents within this channel.
   const onNavigate = useCanvasNavigation(channelId);
 
+  // Comment mode: the overlay captures element/text targets; each becomes a
+  // queued annotation (chip + pin) that rides the next edit instruction.
+  const [annotationMode, setAnnotationMode] = useState(false);
+  const annotations = useCanvasAnnotations(dashboardId);
+  const addAnnotation = useCanvasAnnotationsStore((s) => s.add);
+  const onAnnotationTarget = useCallback(
+    (target: CanvasAnnotationTarget) => {
+      addAnnotation(dashboardId, target);
+      // Reveal the composer so the comment can be typed right away.
+      setCollapsed(false);
+    },
+    [addAnnotation, dashboardId, setCollapsed],
+  );
+  const annotationPins = useMemo(
+    () =>
+      annotations.map((a, i) => ({
+        id: a.id,
+        n: i + 1,
+        selector:
+          a.target.type === "element"
+            ? a.target.selector
+            : a.target.ancestorSelector,
+      })),
+    [annotations],
+  );
+
   // The edit composer's editor handle, so self-repair can prefill it.
   const editorRef = useRef<EditorHandle>(null);
   const askAgentToFix = () => {
@@ -309,6 +343,26 @@ export function FreeformCanvasView({
                   {isResetting ? "Resetting…" : "Reset to default"}
                 </Button>
               )}
+              {showCanvas && (
+                <Tooltip
+                  content={
+                    annotationMode
+                      ? "Exit comment mode"
+                      : "Comment on elements — click anything in the canvas"
+                  }
+                >
+                  <Button
+                    size="icon"
+                    variant={annotationMode ? "primary" : "default"}
+                    aria-label="Comment mode"
+                    className="ml-1"
+                    disabled={isGenerating}
+                    onClick={() => setAnnotationMode((v) => !v)}
+                  >
+                    <CursorClickIcon size={16} />
+                  </Button>
+                </Tooltip>
+              )}
             </Flex>
             <Flex align="center" gap="2">
               {isGenerating && effectiveTaskId ? (
@@ -383,6 +437,9 @@ export function FreeformCanvasView({
                 onError={onError}
                 onRendered={onRendered}
                 onNavigate={onNavigate}
+                annotationMode={annotationMode}
+                annotationPins={annotationPins}
+                onAnnotationTarget={onAnnotationTarget}
               />
             </Box>
           ) : (
diff --git a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
index c56b124bcb..98f56a9b28 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
@@ -1,5 +1,11 @@
+import { XIcon } from "@phosphor-icons/react";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@posthog/quill";
 import { useGenerateFreeformCanvas } from "@posthog/ui/features/canvas/hooks/useGenerateFreeformCanvas";
+import {
+  type QueuedCanvasAnnotation,
+  useCanvasAnnotations,
+  useCanvasAnnotationsStore,
+} from "@posthog/ui/features/canvas/stores/canvasAnnotationsStore";
 import { PromptInput } from "@posthog/ui/features/message-editor/components/PromptInput";
 import type { EditorHandle } from "@posthog/ui/features/message-editor/types";
 import {
@@ -50,6 +56,13 @@ export const FreeformGenerateBar = forwardRef<
     channelName,
   });
 
+  // Queued comment-mode annotations for this canvas: shown as chips with an
+  // inline comment field, drained into the next instruction on submit.
+  const annotations = useCanvasAnnotations(dashboardId);
+  const setAnnotationComment = useCanvasAnnotationsStore((s) => s.setComment);
+  const removeAnnotation = useCanvasAnnotationsStore((s) => s.remove);
+  const clearAnnotations = useCanvasAnnotationsStore((s) => s.clear);
+
   // On a FIRST build we seed the agent with a known-good starter scaffold by
   // default (faster, more consistent than authoring from scratch). Uncheck to
   // opt out and have the agent build from a blank canvas. Only meaningful on an
@@ -72,12 +85,36 @@ export const FreeformGenerateBar = forwardRef<
       currentCode,
       useStarter: !isEdit && useStarter,
       workspaceMode,
+      annotations: annotations.map((a, i) => ({
+        n: i + 1,
+        comment: a.comment.trim(),
+        target: a.target,
+      })),
     });
-    if (taskId) onStarted?.(taskId);
+    if (taskId) {
+      clearAnnotations(dashboardId);
+      onStarted?.(taskId);
+    }
   };
 
   return (
     <div className="flex flex-col gap-1.5">
+      {annotations.length > 0 && (
+        <div className="flex flex-col gap-1">
+          {annotations.map((a, i) => (
+            <AnnotationChip
+              key={a.id}
+              n={i + 1}
+              annotation={a}
+              disabled={isStarting}
+              onComment={(comment) =>
+                setAnnotationComment(dashboardId, a.id, comment)
+              }
+              onRemove={() => removeAnnotation(dashboardId, a.id)}
+            />
+          ))}
+        </div>
+      )}
       <PromptInput
         ref={ref}
         sessionId={sessionId}
@@ -104,21 +141,92 @@ export const FreeformGenerateBar = forwardRef<
       )}
       {/* Dev-only: pick local vs cloud so a local build can be tested pre-merge. */}
       {import.meta.env.DEV && (
-        <Tooltip>
-          <TooltipTrigger render={<div className="self-start px-1" />}>
-            <WorkspaceModeSelect
-              value={workspaceMode}
-              onChange={setWorkspaceMode}
-              overrideModes={["local", "cloud"]}
-              disabled={isStarting}
-              size="1"
-            />
-          </TooltipTrigger>
-          <TooltipContent>
-            Dev mode only — generation always runs in the cloud in production.
-          </TooltipContent>
-        </Tooltip>
+        <DevWorkspaceModePicker
+          workspaceMode={workspaceMode}
+          setWorkspaceMode={setWorkspaceMode}
+          isStarting={isStarting}
+        />
       )}
     </div>
   );
 });
+
+// A queued comment-mode annotation: numbered pin badge (matching the in-canvas
+// pin), a bounded label of what was targeted, an inline comment field, remove.
+function AnnotationChip({
+  n,
+  annotation,
+  disabled,
+  onComment,
+  onRemove,
+}: {
+  n: number;
+  annotation: QueuedCanvasAnnotation;
+  disabled: boolean;
+  onComment: (comment: string) => void;
+  onRemove: () => void;
+}) {
+  const t = annotation.target;
+  const label =
+    t.type === "element"
+      ? `<${t.tag}> ${t.text || t.ariaLabel || t.selector}`
+      : `“${t.text}”`;
+  return (
+    <div className="flex items-center gap-1.5 rounded-md border border-border bg-muted/50 px-1.5 py-1">
+      <span className="flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-primary font-semibold text-[10px] text-primary-foreground">
+        {n}
+      </span>
+      <span
+        className="max-w-36 shrink-0 truncate text-muted-foreground text-xs"
+        title={label}
+      >
+        {label}
+      </span>
+      <input
+        className="min-w-0 flex-1 bg-transparent text-xs outline-none placeholder:text-muted-foreground"
+        placeholder="Add a comment…"
+        value={annotation.comment}
+        disabled={disabled}
+        onChange={(e) => onComment(e.target.value)}
+      />
+      <button
+        type="button"
+        aria-label="Remove annotation"
+        className="shrink-0 text-muted-foreground hover:text-foreground"
+        disabled={disabled}
+        onClick={onRemove}
+      >
+        <XIcon size={12} />
+      </button>
+    </div>
+  );
+}
+
+// Dev-only local/cloud picker, unchanged behavior — extracted so the main
+// component stays readable with the annotation chips above the composer.
+function DevWorkspaceModePicker({
+  workspaceMode,
+  setWorkspaceMode,
+  isStarting,
+}: {
+  workspaceMode: WorkspaceMode;
+  setWorkspaceMode: (mode: WorkspaceMode) => void;
+  isStarting: boolean;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger render={<div className="self-start px-1" />}>
+        <WorkspaceModeSelect
+          value={workspaceMode}
+          onChange={setWorkspaceMode}
+          overrideModes={["local", "cloud"]}
+          disabled={isStarting}
+          size="1"
+        />
+      </TooltipTrigger>
+      <TooltipContent>
+        Dev mode only — generation always runs in the cloud in production.
+      </TooltipContent>
+    </Tooltip>
+  );
+}
diff --git a/packages/ui/src/features/canvas/freeform/canvasFrameStore.ts b/packages/ui/src/features/canvas/freeform/canvasFrameStore.ts
index 779d0697b2..565d52bfc1 100644
--- a/packages/ui/src/features/canvas/freeform/canvasFrameStore.ts
+++ b/packages/ui/src/features/canvas/freeform/canvasFrameStore.ts
@@ -1,5 +1,7 @@
 import type {
   CanvasAnalyticsConfig,
+  CanvasAnnotationPin,
+  CanvasAnnotationTarget,
   CanvasNavIntent,
 } from "@posthog/core/canvas/freeformSchemas";
 import { create } from "zustand";
@@ -35,6 +37,9 @@ export interface CanvasFrameInputs {
   onError?: (message: string, stack?: string) => void;
   onRendered?: () => void;
   onNavigate?: (intent: CanvasNavIntent) => void;
+  annotationMode?: boolean;
+  annotationPins?: CanvasAnnotationPin[];
+  onAnnotationTarget?: (target: CanvasAnnotationTarget) => void;
 }
 
 interface CanvasFrameSlot {
diff --git a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
index 78b26e0f26..f8f827bb11 100644
--- a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
+++ b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
@@ -285,6 +285,162 @@ export function buildSandboxDocument(
       ),
     );
 
+    // --- annotation overlay ("comment mode"): host-toggled element/text
+    // targeting for structured canvas feedback. Host-authored and static (never
+    // touched by canvas code paths); lives OUTSIDE #root so app re-renders
+    // never disturb it, and it only observes/captures while the mode is on.
+    const ANNOTATE_ATTRS = ["data-attr", "data-testid", "data-test-id", "id", "aria-label", "name", "role", "placeholder"];
+    let annotationMode = false;
+    let annotationPins = [];
+    const overlayRoot = document.createElement("div");
+    overlayRoot.setAttribute("data-ph-annotate", "");
+    overlayRoot.style.cssText = "position:fixed;inset:0;pointer-events:none;z-index:2147483646;";
+    document.documentElement.appendChild(overlayRoot);
+    const highlightBox = document.createElement("div");
+    highlightBox.style.cssText = "position:fixed;display:none;pointer-events:none;border:1.5px solid var(--primary,#1d4aff);border-radius:4px;background:color-mix(in srgb, var(--primary, #1d4aff) 8%, transparent);";
+    overlayRoot.appendChild(highlightBox);
+    const pinLayer = document.createElement("div");
+    pinLayer.style.cssText = "position:fixed;inset:0;pointer-events:none;";
+    overlayRoot.appendChild(pinLayer);
+
+    const boundText = (t) => (t || "").replace(/\\s+/g, " ").trim().slice(0, 160);
+    // Prefer a stable attribute; fall back to tag + position. Precision is
+    // secondary — the host also captures the text snippet, and the consumer is
+    // the generation agent locating the spot in source it wrote itself.
+    const ownSelector = (el) => {
+      for (const attr of ANNOTATE_ATTRS) {
+        const v = el.getAttribute && el.getAttribute(attr);
+        if (v) return el.tagName.toLowerCase() + "[" + attr + '="' + CSS.escape(v) + '"]';
+      }
+      return null;
+    };
+    const nthSelector = (el) => {
+      let i = 1;
+      let sib = el;
+      while ((sib = sib.previousElementSibling)) {
+        if (sib.tagName === el.tagName) i++;
+      }
+      return el.tagName.toLowerCase() + ":nth-of-type(" + i + ")";
+    };
+    const selectorFor = (el) => {
+      const parts = [];
+      let node = el;
+      while (node && node !== document.body && parts.length < 6) {
+        const own = ownSelector(node);
+        if (own) {
+          parts.unshift(own);
+          const sel = parts.join(" > ");
+          try {
+            if (document.querySelectorAll(sel).length === 1) return sel;
+          } catch {}
+        } else {
+          parts.unshift(nthSelector(node));
+        }
+        node = node.parentElement;
+      }
+      return parts.join(" > ");
+    };
+    const elementTargetFor = (el) => {
+      const attributes = {};
+      for (const attr of ANNOTATE_ATTRS) {
+        const v = el.getAttribute && el.getAttribute(attr);
+        if (v) attributes[attr] = String(v).slice(0, 80);
+      }
+      return {
+        type: "element",
+        selector: selectorFor(el),
+        tag: el.tagName.toLowerCase(),
+        text: boundText(el.innerText),
+        ariaLabel: el.getAttribute("aria-label"),
+        attributes,
+      };
+    };
+    const setAnnotationHighlight = (el) => {
+      if (!el || el === document.body || el === document.documentElement) {
+        highlightBox.style.display = "none";
+        return;
+      }
+      const r = el.getBoundingClientRect();
+      highlightBox.style.display = "block";
+      highlightBox.style.top = r.top - 2 + "px";
+      highlightBox.style.left = r.left - 2 + "px";
+      highlightBox.style.width = r.width + 4 + "px";
+      highlightBox.style.height = r.height + 4 + "px";
+    };
+    const renderAnnotationPins = () => {
+      pinLayer.textContent = "";
+      for (const pin of annotationPins) {
+        let el = null;
+        try {
+          el = document.querySelector(pin.selector);
+        } catch {}
+        if (!el) continue;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) continue;
+        const dot = document.createElement("div");
+        dot.textContent = String(pin.n);
+        dot.style.cssText = "position:fixed;width:18px;height:18px;border-radius:9999px;background:var(--primary,#1d4aff);color:var(--primary-foreground,#fff);font:600 11px ui-sans-serif,system-ui,sans-serif;display:flex;align-items:center;justify-content:center;box-shadow:0 1px 4px rgba(0,0,0,0.3);pointer-events:none;";
+        dot.style.top = r.top - 8 + "px";
+        dot.style.left = r.right - 8 + "px";
+        pinLayer.appendChild(dot);
+      }
+    };
+    let pinsRaf = 0;
+    const schedulePins = () => {
+      if (pinsRaf) return;
+      pinsRaf = requestAnimationFrame(() => {
+        pinsRaf = 0;
+        renderAnnotationPins();
+      });
+    };
+    window.addEventListener("scroll", schedulePins, true);
+    window.addEventListener("resize", schedulePins);
+    // Re-anchor pins when the app's own DOM shifts (accordion, tab switch, …).
+    new MutationObserver(schedulePins).observe(document.getElementById("root"), {
+      subtree: true,
+      childList: true,
+      attributes: true,
+    });
+    document.addEventListener(
+      "mousemove",
+      (e) => {
+        if (!annotationMode) return;
+        setAnnotationHighlight(e.target instanceof Element ? e.target : null);
+      },
+      true,
+    );
+    // Capture-phase, so comment-mode clicks never reach the app's handlers. A
+    // non-collapsed selection wins over the clicked element (drag-select, then
+    // the click that ends it lands here).
+    document.addEventListener(
+      "click",
+      (e) => {
+        if (!annotationMode) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const sel = window.getSelection();
+        const selText = sel && !sel.isCollapsed ? boundText(sel.toString()) : "";
+        if (selText) {
+          const anchor = sel.anchorNode && sel.anchorNode.parentElement;
+          post({
+            type: "annotation-target",
+            target: {
+              type: "text-range",
+              text: selText,
+              ancestorSelector: anchor ? selectorFor(anchor) : "body",
+              ancestorTag: anchor ? anchor.tagName.toLowerCase() : "body",
+            },
+          });
+          sel.removeAllRanges();
+          return;
+        }
+        if (e.target instanceof Element) {
+          post({ type: "annotation-target", target: elementTargetFor(e.target) });
+        }
+      },
+      true,
+    );
+
     // JSX text and attribute strings never process \\uXXXX escapes (they render
     // verbatim, e.g. "\\u00b7" instead of "·"), but generated canvases still
     // contain them despite the prompt rules — decode at transpile time so both
@@ -365,10 +521,12 @@ export function buildSandboxDocument(
         root.render(
           React.createElement(Boundary, null, React.createElement(Comp)),
         );
-        // Let layout settle, then report success.
+        // Let layout settle, then report success (and re-anchor any pins —
+        // a remount replaces the DOM the pins were positioned against).
         requestAnimationFrame(() => {
           if (seq !== mountSeq) return;
           post({ type: "rendered" });
+          schedulePins();
         });
       } catch (err) {
         // Only the latest snapshot reports — a superseded partial's parse error
@@ -387,6 +545,13 @@ export function buildSandboxDocument(
       } else if (d.type === "set-theme") {
         // Re-theme in place — no mount(), so the app keeps all its state.
         applyTheme(d.theme);
+      } else if (d.type === "set-annotation-mode") {
+        annotationMode = !!d.enabled;
+        document.documentElement.style.cursor = annotationMode ? "crosshair" : "";
+        if (!annotationMode) setAnnotationHighlight(null);
+      } else if (d.type === "annotation-pins") {
+        annotationPins = Array.isArray(d.pins) ? d.pins : [];
+        schedulePins();
       } else if (d.type === "data-response") {
         const p = pending.get(d.id);
         if (!p) return;
diff --git a/packages/ui/src/features/canvas/freeformPrompt.test.ts b/packages/ui/src/features/canvas/freeformPrompt.test.ts
index 647f4cb465..0583337adf 100644
--- a/packages/ui/src/features/canvas/freeformPrompt.test.ts
+++ b/packages/ui/src/features/canvas/freeformPrompt.test.ts
@@ -21,19 +21,95 @@ describe("buildFreeformGenerationPrompt", () => {
     expect(extracted?.stripped).toBe("add a retention chart");
     // The authoring contract + publishing rules are collapsed into the tag body.
     expect(extracted?.body).toContain("PUBLISHING");
+    expect(extracted?.body).toContain("canvas_publish");
+  });
+
+  it("routes all builds through checkout → edit file → publish", () => {
+    const prompt = buildFreeformGenerationPrompt(base);
+    const extracted = extractCanvasInstructions(prompt);
+    expect(extracted?.body).toContain("Build a freeform React canvas");
+    expect(extracted?.body).toContain("canvas_checkout");
+    expect(extracted?.body).toContain(`id: "dash-1"`);
+    // Publishing goes through the local tool; the remote MCP publish tool is
+    // named only to steer the agent away from it.
+    expect(extracted?.body).toContain("canvas_publish");
     expect(extracted?.body).toContain(
-      "desktop-file-system-canvas-partial-update",
+      "`desktop-file-system-canvas-partial-update` directly",
     );
   });
 
-  it("folds the current code into the tag when editing", () => {
+  it("has edits work the scratch file instead of embedding the source", () => {
     const prompt = buildFreeformGenerationPrompt({
       ...base,
       currentCode: "export const App = () => null;",
     });
     const extracted = extractCanvasInstructions(prompt);
     expect(extracted?.stripped).toBe("add a retention chart");
-    expect(extracted?.body).toContain("export const App = () => null;");
     expect(extracted?.body).toContain("Edit the freeform React canvas");
+    // The source is no longer folded into the prompt — canvas_checkout fetches
+    // the live code tool-side and the agent edits the scratch file in place.
+    expect(extracted?.body).not.toContain("export const App = () => null;");
+    expect(extracted?.body).toContain("canvas_checkout");
+    expect(extracted?.body).toContain("editing that file");
+    // The stale-publish recovery loop is spelled out.
+    expect(extracted?.body).toContain("version-conflict");
+  });
+
+  it("folds queued annotations into a numbered block, and omits it when empty", () => {
+    const withAnnotations = buildFreeformGenerationPrompt({
+      ...base,
+      currentCode: "export default () => null;",
+      annotations: [
+        {
+          n: 1,
+          comment: "make this smaller",
+          target: {
+            type: "element",
+            selector: '[data-attr="refresh"]',
+            tag: "button",
+            text: "Refresh",
+            ariaLabel: null,
+            attributes: { "data-attr": "refresh" },
+          },
+        },
+        {
+          n: 2,
+          comment: "reword this",
+          target: {
+            type: "text-range",
+            text: "weekly active users",
+            ancestorSelector: "main > p:nth-of-type(2)",
+            ancestorTag: "p",
+          },
+        },
+      ],
+    });
+    const body = extractCanvasInstructions(withAnnotations)?.body ?? "";
+    expect(body).toContain("[Annotations]");
+    expect(body).toContain('1. On <button> "Refresh"');
+    expect(body).toContain('selector: [data-attr="refresh"]');
+    expect(body).toContain("make this smaller");
+    expect(body).toContain('2. On the text "weekly active users"');
+    expect(body).toContain("reword this");
+
+    const without = buildFreeformGenerationPrompt({
+      ...base,
+      currentCode: "export default () => null;",
+    });
+    expect(extractCanvasInstructions(without)?.body).not.toContain(
+      "[Annotations]",
+    );
+  });
+
+  it("seeds the starter scaffold into the checked-out file on a first build", () => {
+    const prompt = buildFreeformGenerationPrompt({
+      ...base,
+      useStarter: true,
+    });
+    const extracted = extractCanvasInstructions(prompt);
+    expect(extracted?.body).toContain("[Starter scaffold]");
+    expect(extracted?.body).toContain("canvas_checkout");
+    // The scaffold rides in the prompt (there is nothing to fetch yet).
+    expect(extracted?.body).toContain("```tsx");
   });
 });
diff --git a/packages/ui/src/features/canvas/freeformPrompt.ts b/packages/ui/src/features/canvas/freeformPrompt.ts
index 32631fc0c7..0c1e74fcdb 100644
--- a/packages/ui/src/features/canvas/freeformPrompt.ts
+++ b/packages/ui/src/features/canvas/freeformPrompt.ts
@@ -1,27 +1,64 @@
 import { freeformSystemPromptFor } from "@posthog/core/canvas/canvasTemplates";
+import type { CanvasAnnotationTarget } from "@posthog/core/canvas/freeformSchemas";
 import { FREEFORM_STARTER_CODE } from "@posthog/core/canvas/freeformStarter";
 
+// A queued comment-mode annotation, ready for the prompt: the pin number the
+// user saw, their comment, and the captured target.
+export interface CanvasAnnotationPromptInput {
+  n: number;
+  comment: string;
+  target: CanvasAnnotationTarget;
+}
+
+// One prompt line per annotation. The selector describes the RENDERED DOM, so
+// the quoted text + stable attributes are the primary locators against source.
+function annotationLine(a: CanvasAnnotationPromptInput): string {
+  const t = a.target;
+  const comment = a.comment || "see the user's request above";
+  if (t.type === "text-range") {
+    return `${a.n}. On the text "${t.text}" (inside <${t.ancestorTag}>, selector: ${t.ancestorSelector}): ${comment}`;
+  }
+  const attrs = Object.entries(t.attributes)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(" ");
+  const label = t.text ? ` "${t.text}"` : "";
+  const hints = [`selector: ${t.selector}`, attrs].filter(Boolean).join("; ");
+  return `${a.n}. On <${t.tag}>${label} (${hints}): ${comment}`;
+}
+
 // Builds the prompt for the task that generates a freeform (React) canvas. Like
 // CONTEXT.md generation, this runs as a normal repo-less agent task (no repo
 // picked up front), so the agent has the default system prompt — the freeform
 // authoring contract
 // (imports, the `ph` data shim, Quill/style rules) therefore has to live in the
 // task's content (its first user message). The canvas is not a file on disk — it
-// lives in PostHog — so the agent publishes the result via the PostHog MCP tool
-// `desktop-file-system-canvas-partial-update` rather than replying with code or
-// writing a file.
+// lives in PostHog — but the agent WORKS on it as a local scratch file through
+// the `canvas_checkout` / `canvas_publish` local tools (posthog-code-tools):
+// checkout writes the live source to a scratch path tool-side and records the
+// base version; the agent applies the change with its native file-editing tools
+// (targeted edits, not a full regeneration — and no transcribing the source
+// through chat); publish reads the file from disk and saves it as the new
+// version, rejecting a publish whose base is stale (a concurrent edit or undo)
+// instead of silently clobbering it.
 export function buildFreeformGenerationPrompt(input: {
   dashboardId: string;
   name: string;
   channelName: string;
   templateId?: string;
   instruction: string;
-  // The current source, when editing an existing canvas. Omitted for a first build.
+  // Present when editing an existing canvas; omitted for a first build. Only
+  // its presence matters — `canvas_checkout` fetches the authoritative source
+  // itself (fresher than anything embedded at task-creation time), so the
+  // content is no longer folded into the prompt.
   currentCode?: string;
   // Default on (opt out via the generate bar): seed a known-good starter
   // scaffold as the agent's baseline on a FIRST build, so it edits a compiling
   // app instead of authoring boilerplate from scratch. Ignored when editing.
   useStarter?: boolean;
+  // Queued comment-mode annotations: parts of the rendered canvas the user
+  // marked, each with a comment. Rendered as a numbered block matching the
+  // pins the user saw.
+  annotations?: CanvasAnnotationPromptInput[];
 }): string {
   const {
     dashboardId,
@@ -31,6 +68,7 @@ export function buildFreeformGenerationPrompt(input: {
     instruction,
     currentCode,
     useStarter,
+    annotations,
   } = input;
 
   const contract = freeformSystemPromptFor(templateId);
@@ -43,16 +81,56 @@ export function buildFreeformGenerationPrompt(input: {
     ? `Edit the freeform React canvas "${name}" in the channel "${channelName}", per the user's request at the start of this message.`
     : `Build a freeform React canvas "${name}" for the channel "${channelName}", per the user's request at the start of this message.`;
 
-  const currentBlock = isEdit
-    ? `\n[Current code] — the canvas as it stands now. Rewrite the WHOLE file with the change applied; do not output a partial file.\n\n\`\`\`tsx\n${currentCode}\n\`\`\`\n`
+  const checkoutStep = `
+[Working copy] — FIRST, check out the canvas: call the \`canvas_checkout\` tool
+(posthog-code-tools) with id "${dashboardId}". It writes the canvas's live
+source to a local scratch file and returns the path.`;
+
+  const editStep = isEdit
+    ? `
+Then apply the user's request by editing that file with your file-editing
+tools. Do not paste the source into chat.
+`
     : "";
 
+  // Structured feedback from the comment-mode overlay: numbered to match the
+  // pins the user saw on the rendered canvas.
+  const annotationsBlock =
+    annotations && annotations.length > 0
+      ? `
+[Annotations] — the user marked specific parts of the RENDERED canvas. Locate
+each in the checked-out source (match primarily by the quoted text and the
+stable attributes — the CSS selector describes the rendered DOM, not the code)
+and apply the comment as a targeted edit:
+${annotations.map(annotationLine).join("\n")}
+`
+      : "";
+
   // First-build only: hand the agent a working scaffold to build ON instead of
   // authoring from zero. It already wires the easy-to-get-wrong bits (date
   // picker, theme tokens, loading skeletons, typed-node result reading).
   const starterBlock =
     !isEdit && useStarter
-      ? `\n[Starter scaffold] — begin from this WORKING baseline instead of authoring from scratch. It already wires the things that are easy to get wrong: the date picker, theme-aware tokens, per-card loading skeletons, and reading a typed-node result correctly. KEEP that wiring; replace the sample "total events" metric and the layout with what the user asked for, and output the COMPLETE rewritten file.\n\n\`\`\`tsx\n${FREEFORM_STARTER_CODE}\n\`\`\`\n`
+      ? `
+[Starter scaffold] — the canvas is empty, so write this WORKING baseline to the
+checked-out path, then build by EDITING that file. It already wires the things
+that are easy to get wrong: the date picker, theme-aware tokens, per-card
+loading skeletons, and reading a typed-node result correctly. KEEP that wiring;
+replace the sample "total events" metric and the layout with what the user
+asked for.
+
+\`\`\`tsx
+${FREEFORM_STARTER_CODE}
+\`\`\`
+`
+      : "";
+
+  const freshBuildStep =
+    !isEdit && !useStarter
+      ? `
+The canvas is empty: author the complete app at the checked-out path and
+iterate on it there with your file-editing tools.
+`
       : "";
 
   // The standing authoring contract + publishing/data rules are the same
@@ -62,22 +140,27 @@ export function buildFreeformGenerationPrompt(input: {
   // inline (see extractCanvasInstructions). Kept after the user's instruction so
   // the request leads, mirroring how channel CONTEXT.md is appended.
   const instructions = `${header}
-${currentBlock}${starterBlock}
+${checkoutStep}${editStep}${annotationsBlock}${starterBlock}${freshBuildStep}
 Follow this authoring contract for the canvas (imports, the \`ph\` data shim, and
 style rules):
 
 ${contract}
 
-PUBLISHING — this OVERRIDES any instruction above about replying with the code in
-a fenced \`\`\`tsx block. In this task you do NOT reply with the code. When the
-canvas is ready, PUBLISH it by calling the PostHog MCP tool
-\`desktop-file-system-canvas-partial-update\` exactly once with:
+PUBLISHING — the scratch file is only your working copy; the canvas lives in
+PostHog. When it is ready, call the \`canvas_publish\` tool (posthog-code-tools)
+exactly once with:
 - id: "${dashboardId}"
-- code: the COMPLETE single-file React source for the canvas.
+- prompt: one short sentence describing the change.
+
+It reads the scratch file from disk and saves it as the canvas's new version —
+do not paste the code into the tool call or into chat, and do not call
+\`desktop-file-system-canvas-partial-update\` directly. If it fails with a
+version-conflict error, the canvas changed while you worked (another edit, or
+the user's undo): call \`canvas_checkout\` again, re-apply your edits to the
+re-seeded file, then publish again.
 
-The canvas lives in PostHog, not on disk — calling that MCP tool is what saves it.
-Do not write a local file. Verify event/property names via the PostHog MCP before
-using them, and operate only on this project.
+Verify event/property names via the PostHog MCP before using them, and operate
+only on this project.
 
 DATA — for each metric, first SAVE an insight via the PostHog MCP insight tools
 (prefer an insight query type — Trends, Funnels, Retention, web-analytics kinds —
diff --git a/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts b/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
index 3ae5404d7b..be6b1fcadb 100644
--- a/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
+++ b/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
@@ -16,7 +16,10 @@ import {
   type WorkspaceMode,
 } from "@posthog/shared";
 import { useAuthStateValue } from "@posthog/ui/features/auth/store";
-import { buildFreeformGenerationPrompt } from "@posthog/ui/features/canvas/freeformPrompt";
+import {
+  buildFreeformGenerationPrompt,
+  type CanvasAnnotationPromptInput,
+} from "@posthog/ui/features/canvas/freeformPrompt";
 import { useChannelTaskMutations } from "@posthog/ui/features/canvas/hooks/useChannelTasks";
 import {
   isPlaceholderCanvasName,
@@ -92,6 +95,8 @@ export function useGenerateFreeformCanvas(args: {
       reasoningLevel?: string;
       // Default on (opt out in the bar): seed the starter scaffold on first build.
       useStarter?: boolean;
+      // Queued comment-mode annotations, folded into the instruction body.
+      annotations?: CanvasAnnotationPromptInput[];
       // Dev-only override (the bar exposes a local/cloud picker in dev so a
       // local build of these features can be tested before merging). Production
       // always runs in the cloud — see the default below.
@@ -107,6 +112,7 @@ export function useGenerateFreeformCanvas(args: {
         adapter = "claude",
         reasoningLevel,
         useStarter,
+        annotations,
         // Defaults to a cloud run — canvas generation should never tie up (or
         // depend on) the local machine, and it's never the sticky last-used
         // workspace mode. The dev-only picker can override to "local" to test a
@@ -147,6 +153,7 @@ export function useGenerateFreeformCanvas(args: {
               instruction,
               currentCode,
               useStarter,
+              annotations,
             }),
             taskDescription: `Generate canvas "${name}"`,
             // Unattended generation: run in auto mode so it doesn't stall on edit-approval prompts.
diff --git a/packages/ui/src/features/canvas/stores/canvasAnnotationsStore.ts b/packages/ui/src/features/canvas/stores/canvasAnnotationsStore.ts
new file mode 100644
index 0000000000..7ddbe5beb0
--- /dev/null
+++ b/packages/ui/src/features/canvas/stores/canvasAnnotationsStore.ts
@@ -0,0 +1,66 @@
+import type { CanvasAnnotationTarget } from "@posthog/core/canvas/freeformSchemas";
+import { create } from "zustand";
+
+// The queued canvas annotations ("comment mode"): targets captured by the
+// sandbox overlay, each with a host-side comment, keyed per canvas. Pure view
+// state — the queue drains into the next generation instruction on submit.
+export interface QueuedCanvasAnnotation {
+  id: string;
+  target: CanvasAnnotationTarget;
+  comment: string;
+}
+
+interface CanvasAnnotationsStore {
+  byDashboard: Record<string, QueuedCanvasAnnotation[]>;
+  add: (dashboardId: string, target: CanvasAnnotationTarget) => void;
+  setComment: (dashboardId: string, id: string, comment: string) => void;
+  remove: (dashboardId: string, id: string) => void;
+  clear: (dashboardId: string) => void;
+}
+
+export const useCanvasAnnotationsStore = create<CanvasAnnotationsStore>()(
+  (set) => ({
+    byDashboard: {},
+    add: (dashboardId, target) =>
+      set((s) => ({
+        byDashboard: {
+          ...s.byDashboard,
+          [dashboardId]: [
+            ...(s.byDashboard[dashboardId] ?? []),
+            { id: crypto.randomUUID(), target, comment: "" },
+          ],
+        },
+      })),
+    setComment: (dashboardId, id, comment) =>
+      set((s) => ({
+        byDashboard: {
+          ...s.byDashboard,
+          [dashboardId]: (s.byDashboard[dashboardId] ?? []).map((a) =>
+            a.id === id ? { ...a, comment } : a,
+          ),
+        },
+      })),
+    remove: (dashboardId, id) =>
+      set((s) => ({
+        byDashboard: {
+          ...s.byDashboard,
+          [dashboardId]: (s.byDashboard[dashboardId] ?? []).filter(
+            (a) => a.id !== id,
+          ),
+        },
+      })),
+    clear: (dashboardId) =>
+      set((s) => ({
+        byDashboard: { ...s.byDashboard, [dashboardId]: [] },
+      })),
+  }),
+);
+
+const EMPTY: QueuedCanvasAnnotation[] = [];
+
+/** The queued annotations for one canvas (stable empty array when none). */
+export function useCanvasAnnotations(
+  dashboardId: string,
+): QueuedCanvasAnnotation[] {
+  return useCanvasAnnotationsStore((s) => s.byDashboard[dashboardId] ?? EMPTY);
+}