From 91708b555c71e8c8af355d927c89dff50eba82b7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 11:09:20 +0000
Subject: [PATCH 1/8] feat: add a Feedback panel that hands canvas notes to a
 coding agent

Notes pin to the current canvas selection and live in one file,
.stacki/feedback.json, inside the open project (git-excluded with the rest
of .stacki/). Claude Code reads that file with its own Read tool, edits the
project, and flips each item's "done"; Stacki re-reads it on window focus,
when the tab opens, and before every write. No server, port or watcher:
the file is the interface, because the agent can already read the project.

- shared/ipc/feedback.ts: the item and file parsers (version 1, bounded,
  ids unique). Agent-appended items may omit createdAt and use keys: [].
- feedback:read / feedback:write: one channel pair through the usual six
  touch points. Main resolves each item's file:line trail from its
  selection keys with selectionTrail on every read and write, and writes
  through writeProjectText so the write is atomic like every project write.
- Every renderer change reads the file fresh, applies itself, then writes,
  so an agent's done flips made in the meantime are not overwritten.
- Feedback rail tab (M), with Copy for agent rendering the handoff text.
- Numbered pins on the canvas for open notes at the current drill-in level;
  their paths join the frame's tracked set so it measures them.

shortcut: pins are index paths, not handle-carried spans; a structural edit
above a pinned node moves the pin to its neighbour. Upgrade by storing a
byte span mapped with shared/engine/mapSpan.ts if notes start living across
editing sessions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 electron/handlers/feedbackHandlers.ts         |  61 ++++++++
 electron/main.ts                              |   2 +
 electron/preload/preloadBridge.ts             |   3 +
 shared/ipc/feedback.ts                        |  47 ++++++
 shared/ipc/ipcPayloads.ts                     |   3 +
 shared/ipc/ipcResults.ts                      |   3 +
 shared/ipc/preloadApi.ts                      |   2 +
 src/app/LeftRail.tsx                          |   6 +-
 src/app/appPanels.ts                          |   1 +
 src/app/appTypes.ts                           |   1 +
 src/app/shell/AppPanes.tsx                    |   2 +
 src/app/shell/AppShell.tsx                    |  20 ++-
 src/app/state/appComposers.ts                 |  10 ++
 src/features/feedback/FeedbackPanel.tsx       | 125 ++++++++++++++++
 src/features/feedback/feedback.css            |  75 ++++++++++
 src/features/feedback/feedbackBridge.ts       |  55 +++++++
 src/features/feedback/feedbackState.ts        | 141 ++++++++++++++++++
 src/features/preview/PreviewOverlays.tsx      |  32 ++++
 src/features/preview/PreviewPane.tsx          |  73 +++++----
 src/features/preview/previewRuntime.ts        |  29 +++-
 src/features/preview/previewViewport.css      |  18 +++
 studio/scripts/shared-source.json             |   1 +
 test/electron/app/mainBoundaries.test.ts      |   5 +-
 .../handlers/feedbackHandlers.test.ts         |  51 +++++++
 test/renderer/feedback/feedback.test.js       |  67 +++++++++
 test/renderer/preview/pinOverlays.test.js     |  50 +++++++
 test/shared/ipc/feedback.test.ts              |  28 ++++
 test/shared/ipc/ipcPayloads.test.ts           |  28 ++++
 28 files changed, 906 insertions(+), 33 deletions(-)
 create mode 100644 electron/handlers/feedbackHandlers.ts
 create mode 100644 shared/ipc/feedback.ts
 create mode 100644 src/features/feedback/FeedbackPanel.tsx
 create mode 100644 src/features/feedback/feedback.css
 create mode 100644 src/features/feedback/feedbackBridge.ts
 create mode 100644 src/features/feedback/feedbackState.ts
 create mode 100644 test/electron/handlers/feedbackHandlers.test.ts
 create mode 100644 test/renderer/feedback/feedback.test.js
 create mode 100644 test/renderer/preview/pinOverlays.test.js
 create mode 100644 test/shared/ipc/feedback.test.ts

diff --git a/electron/handlers/feedbackHandlers.ts b/electron/handlers/feedbackHandlers.ts
new file mode 100644
index 00000000..24d6fc65
--- /dev/null
+++ b/electron/handlers/feedbackHandlers.ts
@@ -0,0 +1,61 @@
+// The Feedback panel's IPC: reading and writing `.stacki/feedback.json`, each
+// item's `file:line` trail resolved fresh from disk on the way in and out, so
+// the agent that reads the file lands on the lines as they are now.
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { assert } from '../../shared/core/assert';
+import {
+  FEEDBACK_FILE_VERSION,
+  parseFeedbackFile,
+  type FeedbackItem,
+  type TrailedFeedbackItem,
+} from '../../shared/ipc/feedback';
+import { writeProjectText } from '../documents/documentWrites';
+import { selectionTrail } from '../documents/pageRequests';
+import { readJson } from '../lib/mainHelpers';
+import { ensureExcluded } from '../preview/previewWorktree';
+import type { MainHost } from './mainHost';
+
+const FEEDBACK_FILE = path.join('.stacki', 'feedback.json');
+
+export function registerFeedbackHandlers({
+  ipcMain,
+  assertInProject,
+}: Pick<MainHost, 'assertInProject' | 'ipcMain'>): void {
+  ipcMain.handle('feedback:read', (_event, { projectPath }) => {
+    const file = assertInProject(path.join(projectPath, FEEDBACK_FILE));
+    if (!fs.existsSync(file)) {
+      return { items: [] };
+    }
+    // A malformed file throws: the renderer shows why rather than emptying it.
+    return { items: withTrails(projectPath, parseFeedbackFile(readJson(file)).items) };
+  });
+  ipcMain.handle('feedback:write', (_event, { projectPath, items }) => {
+    const file = assertInProject(path.join(projectPath, FEEDBACK_FILE));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    ensureExcluded(projectPath);
+    const trailed = withTrails(projectPath, items);
+    const text = JSON.stringify({ version: FEEDBACK_FILE_VERSION, items: trailed }, undefined, 2);
+    writeProjectText(file, text + '\n');
+    return { items: trailed };
+  });
+}
+
+// A key whose node is gone resolves to its file alone; one outside the
+// project resolves to nothing, so its trail is empty.
+export function withTrails(
+  projectPath: string,
+  items: readonly FeedbackItem[],
+): readonly TrailedFeedbackItem[] {
+  const trailed = items.map((item) => ({
+    ...item,
+    trail: selectionTrail({ projectPath, keys: [...item.keys] }) ?? [],
+  }));
+  assert(trailed.length === items.length, 'Every feedback item keeps its place');
+  assert(
+    trailed.every((item) => item.trail.length <= item.keys.length),
+    'A trail has at most one entry per key',
+  );
+  return trailed;
+}
diff --git a/electron/main.ts b/electron/main.ts
index 5b068ac0..5352535d 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -61,6 +61,7 @@ import { Thumbnails, registerThumbnailHandlers } from './handlers/thumbnails';
 import { registerAssetHandlers } from './handlers/assetHandlers';
 import { registerCmsHandlers } from './handlers/cmsHandlers';
 import { registerComponentHandlers } from './handlers/componentHandlers';
+import { registerFeedbackHandlers } from './handlers/feedbackHandlers';
 import { registerContentHandlers } from './handlers/contentHandlers';
 import { registerCssVariableHandlers } from './handlers/cssVariableHandlers';
 import { registerGitHandlers } from './handlers/gitHandlers';
@@ -903,6 +904,7 @@ const host: MainHost = {
 registerAssetHandlers(host);
 registerCmsHandlers(host);
 registerComponentHandlers(host);
+registerFeedbackHandlers(host);
 registerContentHandlers(host);
 registerCssVariableHandlers(host);
 registerGitHandlers(host);
diff --git a/electron/preload/preloadBridge.ts b/electron/preload/preloadBridge.ts
index 207c9b7e..d9e04b0a 100644
--- a/electron/preload/preloadBridge.ts
+++ b/electron/preload/preloadBridge.ts
@@ -92,6 +92,9 @@ function projectBridge() {
 
     // ⇧⌘C — the canvas selection as file:line pointers, for an AI chat.
     copySelection: invoke('selection:copy'),
+    // The Feedback panel's .stacki/feedback.json, trails resolved by main.
+    readFeedback: invoke('feedback:read'),
+    writeFeedback: invoke('feedback:write'),
   } satisfies Partial<PreloadBridge>;
 }
 
diff --git a/shared/ipc/feedback.ts b/shared/ipc/feedback.ts
new file mode 100644
index 00000000..aa5412c0
--- /dev/null
+++ b/shared/ipc/feedback.ts
@@ -0,0 +1,47 @@
+// The Feedback panel's file, `.stacki/feedback.json` in the open project: notes
+// pinned to canvas selections, read and edited by Stacki and by a coding agent
+// alike. The file is the whole interface; nothing listens on a port.
+import { assert } from '../core/assert';
+import { boolean, list, object, optional, record, text } from '../core/boundary';
+import type { Parsed } from '../core/boundary';
+
+export const FEEDBACK_FILE_VERSION = 1;
+
+// `keys` are selection keys (`<file>#<index path>`: the page, each drilled-in
+// host, then the leaf). An agent may append its own items with `keys: []`, so
+// `createdAt` is optional for them; the trail is main's to resolve, never read.
+export const parseFeedbackItem = object({
+  id: text,
+  keys: list(text),
+  label: text,
+  note: text,
+  createdAt: optional(text),
+  done: boolean,
+});
+export type FeedbackItem = Parsed<typeof parseFeedbackItem>;
+
+/** An item with the `file:line` trail main resolved from its keys. */
+export type TrailedFeedbackItem = FeedbackItem & { readonly trail: readonly string[] };
+
+export interface FeedbackFile {
+  readonly version: typeof FEEDBACK_FILE_VERSION;
+  readonly items: readonly FeedbackItem[];
+}
+
+export function parseFeedbackFile(input: unknown): FeedbackFile {
+  const value = record(input);
+  if (value['version'] !== FEEDBACK_FILE_VERSION) {
+    throw new Error(`Feedback file: expected version ${FEEDBACK_FILE_VERSION}`);
+  }
+  const items = list(parseFeedbackItem)(value['items']);
+  // Ids key the list and the pins; two items sharing one would edit each other.
+  if (new Set(items.map((item) => item.id)).size !== items.length) {
+    throw new Error('Feedback file: duplicate item id');
+  }
+  assert(Array.isArray(items), 'Feedback items parse to an array');
+  assert(
+    items.every((item) => typeof item.done === 'boolean'),
+    'Every feedback item says whether it is done',
+  );
+  return { version: FEEDBACK_FILE_VERSION, items };
+}
diff --git a/shared/ipc/ipcPayloads.ts b/shared/ipc/ipcPayloads.ts
index 331a6eb4..ee26a5d9 100644
--- a/shared/ipc/ipcPayloads.ts
+++ b/shared/ipc/ipcPayloads.ts
@@ -12,6 +12,7 @@ import { parseStudioRequestId } from './studioProgress';
 import { parsePropertyChange, propertySource } from '../properties/propertyEditing';
 import { parseEdit, parseEditRequest } from '../engine/editRequest';
 import { parsePreviewRender } from '../page/previewToken';
+import { parseFeedbackItem } from './feedback';
 // Complete invoke-channel inventory. Every main-process listener receives the
 // parsed shape below; payload field names retain the existing renderer protocol.
 import {
@@ -179,6 +180,8 @@ export const IPC_PAYLOADS = {
   'dev:probe': pathText,
   'dev:start': pathText,
   'dev:stop': nothing,
+  'feedback:read': object({ ...project }),
+  'feedback:write': object({ ...project, items: list(parseFeedbackItem) }),
   'git:allFiles': object({ ...project }),
   'git:checkout': object({ ...branch, create: maybeFlag, parkFirst: maybeFlag }),
   'git:commit': object({ ...project, message: text, paths: optional(list(pathText)) }),
diff --git a/shared/ipc/ipcResults.ts b/shared/ipc/ipcResults.ts
index fd97ebb8..0cc9c435 100644
--- a/shared/ipc/ipcResults.ts
+++ b/shared/ipc/ipcResults.ts
@@ -14,6 +14,7 @@ import type { ComponentProperties } from '../properties/propertyEditing';
 import type { PreviewVerdict } from '../page/previewToken';
 import type { Result } from '../core/result';
 import type { Data } from '../core/boundary';
+import type { TrailedFeedbackItem } from './feedback';
 import {
   type WireAssetEntry,
   type WireCmsFile,
@@ -357,6 +358,8 @@ export interface IpcResults {
   readonly 'dev:stop': {
     readonly ok: true;
   };
+  readonly 'feedback:read': { readonly items: readonly TrailedFeedbackItem[] };
+  readonly 'feedback:write': { readonly items: readonly TrailedFeedbackItem[] };
   readonly 'git:allFiles': ReadonlyArray<
     WireProjectFile &
       WireFileDescription & {
diff --git a/shared/ipc/preloadApi.ts b/shared/ipc/preloadApi.ts
index ec88275a..4b149327 100644
--- a/shared/ipc/preloadApi.ts
+++ b/shared/ipc/preloadApi.ts
@@ -36,6 +36,8 @@ interface InvokeChannels {
   readonly readSourceText: 'src:readText';
   readonly writeSourceText: 'src:writeText';
   readonly copySelection: 'selection:copy';
+  readonly readFeedback: 'feedback:read';
+  readonly writeFeedback: 'feedback:write';
   readonly listCms: 'cms:list';
   readonly readCms: 'cms:read';
   readonly writeCms: 'cms:write';
diff --git a/src/app/LeftRail.tsx b/src/app/LeftRail.tsx
index 7a389500..75890437 100644
--- a/src/app/LeftRail.tsx
+++ b/src/app/LeftRail.tsx
@@ -10,6 +10,7 @@ import {
   VariableIcon,
   CodeIcon,
   HistoryIcon,
+  CommentIcon,
 } from '../ui/Icons';
 
 const TABS = [
@@ -22,6 +23,7 @@ const TABS = [
   { id: 'variables', title: 'Variables', shortcut: '⌥V', Icon: VariableIcon },
   { id: 'code', title: 'Code', shortcut: 'C', Icon: CodeIcon },
   { id: 'history', title: 'Git', shortcut: '⌥H', Icon: HistoryIcon },
+  { id: 'feedback', title: 'Feedback', shortcut: 'M', Icon: CommentIcon },
 ] as const;
 export type RailTab = (typeof TABS)[number]['id'];
 
@@ -101,7 +103,7 @@ function useRailKeys(
   { componentOpen }: { readonly componentOpen: boolean },
   onSelect: (tab: RailTab) => void,
 ): void {
-  // P / Z / ⇧A / J / ⌥C / ⌥H toggle the panels (ignored while typing in a field).
+  // P / Z / ⇧A / J / M / ⌥C / ⌥H toggle the panels (ignored while typing in a field).
   useEffect(() => {
     const onKey = (event: KeyboardEvent): void => {
       if (event.metaKey || event.ctrlKey) {
@@ -143,6 +145,8 @@ function useRailKeys(
         id = 'assets';
       } else if (key === 'c' && !event.shiftKey) {
         id = 'code';
+      } else if (key === 'm' && !event.shiftKey) {
+        id = 'feedback';
       }
       if (id) {
         event.preventDefault();
diff --git a/src/app/appPanels.ts b/src/app/appPanels.ts
index 34fd2e4c..5e045eae 100644
--- a/src/app/appPanels.ts
+++ b/src/app/appPanels.ts
@@ -13,4 +13,5 @@ export const CmsView = lazyPanel(() => import('../features/cms/CmsView'));
 export const ContentView = lazyPanel(() => import('../features/content/ContentView'));
 export const VariablesPanel = lazyPanel(() => import('../features/variables/VariablesPanel'));
 export const VariablesView = lazyPanel(() => import('../features/variables/VariablesView'));
+export const FeedbackPanel = lazyPanel(() => import('../features/feedback/FeedbackPanel'));
 export const CodePanel = lazyPanel(() => import('../features/code/CodePanel'));
diff --git a/src/app/appTypes.ts b/src/app/appTypes.ts
index 16c29103..4042d231 100644
--- a/src/app/appTypes.ts
+++ b/src/app/appTypes.ts
@@ -51,6 +51,7 @@ export type LeftTab =
   | 'variables'
   | 'code'
   | 'history'
+  | 'feedback'
   | undefined;
 export type RightTab = 'style' | 'settings';
 export type DevStatus = 'off' | 'starting' | 'on';
diff --git a/src/app/shell/AppPanes.tsx b/src/app/shell/AppPanes.tsx
index 893e676b..228e0824 100644
--- a/src/app/shell/AppPanes.tsx
+++ b/src/app/shell/AppPanes.tsx
@@ -59,6 +59,8 @@ export function CanvasPane({ app }: { readonly app: ShellView }) {
         navigatorSelectionTick={app.navigatorSelectionTick}
         navHoverPath={app.pathFor(hoverNodeId)}
         overlayInfo={app.overlayInfo}
+        pins={app.feedback.pins}
+        onSelectPin={(pin) => selectCanvasPath(app, pin.path, { outside: false })}
         focusPath={app.focusPath}
         focusOcc={app.focusOcc}
         focusWhole={app.focusWhole}
diff --git a/src/app/shell/AppShell.tsx b/src/app/shell/AppShell.tsx
index dd967146..6d1c059b 100644
--- a/src/app/shell/AppShell.tsx
+++ b/src/app/shell/AppShell.tsx
@@ -33,7 +33,7 @@ import type { HistoryCommit, HistoryCommitFile } from '../../features/history/hi
 import { currentDesktopPlatform, shortcutLabel } from '../../lib/shortcutLabel';
 import { type LeftTab } from '../appTypes';
 import { openExternalURL, restoreProjectFile, restoreProjectVersion } from '../../ipc/appBridge';
-import { CmsPanel, VariablesPanel, CodePanel } from '../appPanels';
+import { CmsPanel, VariablesPanel, CodePanel, FeedbackPanel } from '../appPanels';
 import {
   CanvasPane,
   CanvasCovers,
@@ -42,6 +42,7 @@ import {
   CodeWindowHost,
   ConflictNotice,
   BusyOverlay,
+  selectCanvasPath,
 } from './AppPanes';
 import type { AppView, ShellView } from '../App';
 
@@ -332,6 +333,7 @@ export function LeftPanel({ app, tab }: { readonly app: ShellView; readonly tab:
       )}
       {tab === 'code' && <CodeTab app={app} />}
       {tab === 'history' && <HistoryTab app={app} />}
+      {tab === 'feedback' && <FeedbackTab app={app} />}
       {tab === 'assets' && (
         <AssetsPanel
           project={app.project}
@@ -522,6 +524,22 @@ export function CodeTab({ app }: { readonly app: ShellView }) {
   );
 }
 
+export function FeedbackTab({ app }: { readonly app: ShellView }) {
+  return (
+    <FeedbackPanel
+      feedback={app.feedback}
+      target={app.overlayInfo(app.pathFor(app.selectedId) ?? '')?.label}
+      selectedKey={app.selectionKeysRef.current.at(-1)}
+      onSelectPin={(pin) => {
+        selectCanvasPath(app, pin.path, { outside: false });
+        // Selecting reveals the node in the Navigator; a note's row keeps its panel.
+        app.setLeftTab('feedback');
+      }}
+      showToast={app.showToast}
+    />
+  );
+}
+
 export function HistoryTab({ app }: { readonly app: ShellView }) {
   return (
     <HistoryPanel
diff --git a/src/app/state/appComposers.ts b/src/app/state/appComposers.ts
index ef2da019..f3ffcbfb 100644
--- a/src/app/state/appComposers.ts
+++ b/src/app/state/appComposers.ts
@@ -33,6 +33,7 @@ import {
   useSelectionPaths,
   useOverlayInfo,
 } from './appViewModel';
+import { useFeedback } from '../../features/feedback/feedbackState';
 
 // Every piece of the app's state and behaviour, in the order its hooks run.
 export function useAppScope() {
@@ -45,6 +46,14 @@ export function useAppScope() {
   const propertyEdits = usePropertyEdits(coreState, lifecycle, history, nodeEdits);
   const pageOps = usePageOps(coreState, lifecycle, navigation, history, nodeEdits, shortcuts);
   const viewModel = useViewModel(coreState, lifecycle, shortcuts, pageOps);
+  // After the view model: it sets the selection keys this render pins notes to.
+  const feedback = useFeedback({
+    projectPath: coreState.project?.path,
+    selectionKeys: coreState.selectionKeysRef.current,
+    editedRel: viewModel.editedRel,
+    label: viewModel.overlayInfo(viewModel.pathFor(coreState.selectedId) ?? '')?.label,
+    showToast: lifecycle.showToast,
+  });
   return {
     ...coreState,
     ...lifecycle,
@@ -55,6 +64,7 @@ export function useAppScope() {
     ...propertyEdits,
     ...pageOps,
     ...viewModel,
+    ...feedback,
   };
 }
 
diff --git a/src/features/feedback/FeedbackPanel.tsx b/src/features/feedback/FeedbackPanel.tsx
new file mode 100644
index 00000000..8d78fe0b
--- /dev/null
+++ b/src/features/feedback/FeedbackPanel.tsx
@@ -0,0 +1,125 @@
+import React, { useEffect, useState } from 'react';
+import type { KeyboardEvent } from 'react';
+import type { TrailedFeedbackItem } from '../../../shared/ipc/feedback';
+import { CheckIcon, CloseIcon } from '../../ui/Icons';
+import { renderHandoff } from './feedbackBridge';
+import type { FeedbackPin, useFeedback } from './feedbackState';
+import './feedback.css';
+
+interface FeedbackPanelProps {
+  readonly feedback: ReturnType<typeof useFeedback>['feedback'];
+  /** What a new note attaches to: the selected node's name, or the page. */
+  readonly target: string | undefined;
+  /** The current selection's leaf key; its rows are highlighted. */
+  readonly selectedKey: string | undefined;
+  readonly onSelectPin: (pin: FeedbackPin) => void;
+  readonly showToast: (message: string, kind: 'success' | 'error') => void;
+}
+
+// Notes pinned to canvas selections, kept in .stacki/feedback.json for a coding
+// agent: select an element, type, press Enter; Copy for agent hands them over.
+export default function FeedbackPanel(props: FeedbackPanelProps) {
+  const { feedback } = props;
+  const [draft, setDraft] = useState('');
+  const { reload } = feedback;
+  // Opening the tab catches up with what an agent changed in the file.
+  useEffect(() => void reload(), [reload]);
+  const open = feedback.items.filter((item) => !item.done);
+  const done = feedback.items.filter((item) => item.done);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>): void => {
+    if (event.key !== 'Enter' || event.shiftKey) {
+      return;
+    }
+    event.preventDefault();
+    const note = draft.trim();
+    if (note) {
+      setDraft('');
+      void feedback.add(note);
+    }
+  };
+  const copy = async (): Promise<void> => {
+    try {
+      await navigator.clipboard.writeText(renderHandoff(feedback.items));
+      props.showToast('Copied. Paste it into Claude Code in the project.', 'success');
+    } catch {
+      props.showToast('Could not copy the feedback.', 'error');
+    }
+  };
+  return (
+    <div className="panel-section grow">
+      <div className="panel-header">
+        <h2>Feedback</h2>
+        <button className="feedback-copy" disabled={open.length === 0} onClick={() => void copy()}>
+          Copy for agent
+        </button>
+      </div>
+      <div className="panel-body feedback-body">
+        <textarea
+          className="feedback-input"
+          value={draft}
+          placeholder={props.target ? `Note on ${props.target}` : 'Note on this page'}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={onKeyDown}
+        />
+        {open.map((item, index) => (
+          <FeedbackRow key={item.id} item={item} number={index + 1} {...props} />
+        ))}
+        {done.length > 0 && (
+          <div className="feedback-done-head">
+            <span>Done</span>
+            <button onClick={() => void feedback.clearDone()}>Clear done</button>
+          </div>
+        )}
+        {done.map((item) => (
+          <FeedbackRow key={item.id} item={item} number={undefined} {...props} />
+        ))}
+        <p className="feedback-path">.stacki/feedback.json</p>
+      </div>
+    </div>
+  );
+}
+
+function FeedbackRow(
+  props: FeedbackPanelProps & {
+    readonly item: TrailedFeedbackItem;
+    readonly number: number | undefined;
+  },
+) {
+  const { item, feedback } = props;
+  const pin = feedback.pins.find((candidate) => candidate.id === item.id);
+  const selected = item.keys.at(-1) === props.selectedKey ? ' is-selected' : '';
+  return (
+    <div
+      className={`feedback-row${item.done ? ' is-done' : ''}${selected}`}
+      onClick={() => pin && props.onSelectPin(pin)}
+    >
+      <span className="feedback-number">{props.number ?? ''}</span>
+      <div className="feedback-main">
+        <div className="feedback-label">
+          {item.label}
+          <span className="feedback-where">{item.trail.at(-1) ?? ''}</span>
+        </div>
+        <div className="feedback-note">{item.note}</div>
+      </div>
+      <button
+        aria-label={item.done ? 'Reopen' : 'Done'}
+        onClick={(event) => {
+          event.stopPropagation();
+          void feedback.toggleDone(item.id);
+        }}
+      >
+        <CheckIcon size={12} />
+      </button>
+      <button
+        aria-label="Remove"
+        onClick={(event) => {
+          event.stopPropagation();
+          void feedback.remove(item.id);
+        }}
+      >
+        <CloseIcon size={12} />
+      </button>
+    </div>
+  );
+}
diff --git a/src/features/feedback/feedback.css b/src/features/feedback/feedback.css
new file mode 100644
index 00000000..f8caa5e3
--- /dev/null
+++ b/src/features/feedback/feedback.css
@@ -0,0 +1,75 @@
+/* The Feedback panel, after the History panel's list styles. */
+.feedback-body {
+  padding: 0 8px 12px;
+}
+.feedback-input {
+  width: 100%;
+  min-height: 52px;
+  resize: vertical;
+  margin-bottom: 8px;
+  padding: 6px 8px;
+  font: 11.5px/1.4 var(--font);
+  color: var(--text);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+.feedback-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 6px;
+  padding: 6px 4px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+.feedback-row:hover {
+  background: var(--bg-hover);
+}
+.feedback-row.is-selected {
+  background: var(--accent-soft);
+}
+.feedback-row.is-done {
+  opacity: 0.45;
+}
+.feedback-number {
+  min-width: 14px;
+  font-size: 10.5px;
+  font-weight: 600;
+  color: var(--accent);
+}
+.feedback-main {
+  flex: 1;
+  min-width: 0;
+  font-size: 11.5px;
+  line-height: 1.4;
+}
+.feedback-label {
+  color: var(--text-dim);
+}
+.feedback-where {
+  margin-left: 6px;
+  font-family: var(--mono);
+  font-size: 10px;
+  color: var(--text-faint);
+}
+.feedback-note {
+  color: var(--text);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.feedback-row button {
+  padding: 2px;
+  color: var(--text-faint);
+}
+.feedback-done-head,
+.feedback-path {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 10px;
+  padding: 0 4px;
+  font-size: 10.5px;
+  color: var(--text-faint);
+}
+.feedback-path {
+  font-family: var(--mono);
+}
diff --git a/src/features/feedback/feedbackBridge.ts b/src/features/feedback/feedbackBridge.ts
new file mode 100644
index 00000000..72e78e93
--- /dev/null
+++ b/src/features/feedback/feedbackBridge.ts
@@ -0,0 +1,55 @@
+// The Feedback file through main: read, write, and the replies parsed before
+// the panel trusts them. Also the text Copy for agent puts on the clipboard.
+import { list, record, text } from '../../../shared/core/boundary';
+import { parseFeedbackItem } from '../../../shared/ipc/feedback';
+import type { FeedbackItem, TrailedFeedbackItem } from '../../../shared/ipc/feedback';
+import { parseIpcPayload } from '../../../shared/ipc/ipcPayloads';
+import type { Result } from '../../../shared/core/result';
+import { cleanError } from '../../lib/cleanError';
+
+export function parseFeedbackReply(input: unknown): readonly TrailedFeedbackItem[] {
+  return list((entry) => ({
+    ...parseFeedbackItem(entry),
+    trail: list(text)(record(entry)['trail']),
+  }))(record(input)['items']);
+}
+
+export function readFeedback(projectPath: string) {
+  const payload = parseIpcPayload('feedback:read', { projectPath });
+  return feedbackRequest(() => window.avb.readFeedback(payload));
+}
+
+export function writeFeedback(projectPath: string, items: readonly FeedbackItem[]) {
+  // The trail is main's to resolve; the payload carries only the item fields.
+  const payload = parseIpcPayload('feedback:write', { projectPath, items });
+  return feedbackRequest(() => window.avb.writeFeedback(payload));
+}
+
+/** The one paste that starts the agent: the protocol, then each open item. */
+export function renderHandoff(items: readonly TrailedFeedbackItem[]): string {
+  const open = items.filter((item) => !item.done);
+  const lines = open.map((item, index) => {
+    const where = item.trail.length > 0 ? item.trail.join(' › ') : '(no source location)';
+    return `${index + 1}. ${where} (${item.label}): ${item.note}`;
+  });
+  return [
+    `Address the open items in .stacki/feedback.json (${open.length} open). For each item, ` +
+      'open every file:line in its trail — the last entry is the element, the earlier ones ' +
+      'are the page and the component instances it sits in — make the change, then set ' +
+      'that item\'s "done" to true in the file.',
+    '',
+    ...lines,
+  ].join('\n');
+}
+
+async function feedbackRequest(
+  invoke: () => Promise<unknown>,
+): Promise<Result<readonly TrailedFeedbackItem[], string>> {
+  let response: unknown;
+  try {
+    response = await invoke();
+  } catch (error: unknown) {
+    return { ok: false, error: cleanError(error) };
+  }
+  return { ok: true, value: parseFeedbackReply(response) };
+}
diff --git a/src/features/feedback/feedbackState.ts b/src/features/feedback/feedbackState.ts
new file mode 100644
index 00000000..ecd166a4
--- /dev/null
+++ b/src/features/feedback/feedbackState.ts
@@ -0,0 +1,141 @@
+// The Feedback list the panel and the canvas share. The file is the only
+// state: every change reads it fresh, applies the change, and writes it back,
+// so an agent's edits made in the meantime (done flips, its own items) survive.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { assert } from '../../../shared/core/assert';
+import type { FeedbackItem, TrailedFeedbackItem } from '../../../shared/ipc/feedback';
+import { readFeedback, writeFeedback } from './feedbackBridge';
+
+export interface FeedbackPin {
+  readonly id: string;
+  /** The marker path the canvas frame measures and selects by. */
+  readonly path: string;
+  /** The item's 1-based number among the open items, as the list shows it. */
+  readonly index: number;
+  readonly note: string;
+}
+
+interface FeedbackContext {
+  readonly projectPath: string | undefined;
+  /** The current selection keys: each drilled-in host, then the leaf. */
+  readonly selectionKeys: readonly string[];
+  readonly editedRel: string | undefined;
+  /** The selected node's name, for a new note's label. */
+  readonly label: string | undefined;
+  readonly showToast: (message: string, kind: 'error') => void;
+}
+
+export function useFeedback(context: FeedbackContext) {
+  const { projectPath, selectionKeys, editedRel, label, showToast } = context;
+  const [items, setItems] = useState<readonly TrailedFeedbackItem[]>([]);
+  // Replies for a project that is no longer open are dropped.
+  const projectRef = useRef(projectPath);
+  projectRef.current = projectPath;
+
+  const reload = useCallback(async (): Promise<void> => {
+    const requested = projectPath;
+    if (!requested) {
+      setItems([]);
+      return;
+    }
+    const result = await readFeedback(requested);
+    if (projectRef.current !== requested) {
+      return;
+    }
+    if (result.ok) {
+      setItems(result.value);
+    } else {
+      showToast(result.error, 'error');
+    }
+  }, [projectPath, showToast]);
+
+  const change = useCallback(
+    async (apply: (items: readonly FeedbackItem[]) => readonly FeedbackItem[]): Promise<void> => {
+      if (!projectPath) {
+        return;
+      }
+      const current = await readFeedback(projectPath);
+      const written = current.ok ? await writeFeedback(projectPath, apply(current.value)) : current;
+      if (projectRef.current !== projectPath) {
+        return;
+      }
+      if (written.ok) {
+        setItems(written.value);
+      } else {
+        showToast(written.error, 'error');
+      }
+    },
+    [projectPath, showToast],
+  );
+
+  useEffect(() => {
+    void reload();
+    const onFocus = (): void => void reload();
+    window.addEventListener('focus', onFocus);
+    return () => window.removeEventListener('focus', onFocus);
+  }, [reload]);
+
+  const keysKey = selectionKeys.join('\n');
+  const pins = useMemo(
+    () => feedbackPins(items, { selectionKeys: keysKey.split('\n'), editedRel }),
+    [items, keysKey, editedRel],
+  );
+  const add = (note: string): Promise<void> =>
+    change((previous) => [...previous, newItem(selectionKeys, label ?? 'page', note)]);
+  const toggleDone = (id: string): Promise<void> =>
+    change((previous) =>
+      previous.map((item) => (item.id === id ? { ...item, done: !item.done } : item)),
+    );
+  const remove = (id: string): Promise<void> =>
+    change((previous) => previous.filter((item) => item.id !== id));
+  const clearDone = (): Promise<void> =>
+    change((previous) => previous.filter((item) => !item.done));
+  return { feedback: { items, pins, reload, add, toggleDone, remove, clearDone } };
+}
+
+function newItem(keys: readonly string[], label: string, note: string): FeedbackItem {
+  return {
+    id: crypto.randomUUID().slice(0, 8),
+    keys: [...keys],
+    label,
+    note,
+    createdAt: new Date().toISOString(),
+    done: false,
+  };
+}
+
+/**
+ * The open items that draw on the canvas: those pinned at the current level of
+ * the editing stack (same drilled-in hosts) to a node of the open file.
+ * Everything else stays in the list without a pin.
+ */
+export function feedbackPins(
+  items: readonly TrailedFeedbackItem[],
+  at: { readonly selectionKeys: readonly string[]; readonly editedRel: string | undefined },
+): readonly FeedbackPin[] {
+  const currentLeaf = at.selectionKeys.at(-1);
+  if (currentLeaf === undefined) {
+    return [];
+  }
+  const currentHosts = at.selectionKeys.slice(0, -1).join('\n');
+  const openFile = currentLeaf.slice(0, currentLeaf.indexOf('#'));
+  const pins: FeedbackPin[] = [];
+  items
+    .filter((item) => !item.done)
+    .forEach((item, position) => {
+      const leaf = item.keys.at(-1);
+      if (leaf === undefined || item.keys.slice(0, -1).join('\n') !== currentHosts) {
+        return;
+      }
+      const hash = leaf.indexOf('#');
+      const indexPath = leaf.slice(hash + 1);
+      // A page-level note (`file#`) or the frontmatter has no box to pin to.
+      if (hash === -1 || leaf.slice(0, hash) !== openFile || !/^\d+(\.\d+)*$/.test(indexPath)) {
+        return;
+      }
+      const path = at.editedRel ? `${at.editedRel}|${indexPath}` : indexPath;
+      pins.push({ id: item.id, path, index: position + 1, note: item.note });
+    });
+  assert(pins.length <= items.length, 'At most one pin per item');
+  return pins;
+}
diff --git a/src/features/preview/PreviewOverlays.tsx b/src/features/preview/PreviewOverlays.tsx
index 4c3020cb..87746729 100644
--- a/src/features/preview/PreviewOverlays.tsx
+++ b/src/features/preview/PreviewOverlays.tsx
@@ -28,6 +28,14 @@ export interface OverlayInfo {
   readonly bound: boolean;
 }
 
+/** A Feedback note drawn on the canvas at its node's first box. */
+export interface PinOverlay {
+  readonly id: string;
+  readonly path: string;
+  readonly index: number;
+  readonly note: string;
+}
+
 export interface SpacingHover {
   readonly kind: 'padding' | 'margin' | 'gap';
   readonly sides?: readonly string[];
@@ -54,6 +62,8 @@ interface PreviewOverlaysProps {
   readonly focusPath: string | undefined;
   readonly focusWhole: boolean;
   readonly overlayInfo?: (path: string) => OverlayInfo | undefined;
+  readonly pins?: readonly PinOverlay[] | undefined;
+  readonly onSelectPin?: ((pin: PinOverlay) => void) | undefined;
 }
 
 export function PreviewOverlays(props: PreviewOverlaysProps) {
@@ -64,10 +74,32 @@ export function PreviewOverlays(props: PreviewOverlaysProps) {
       )}
       <SpacingOverlays {...props} />
       <NodeOutlines {...props} />
+      <PinOverlays {...props} />
     </>
   );
 }
 
+// A pin whose node reported no box (another branch, off the page) draws nothing.
+function PinOverlays(props: PreviewOverlaysProps) {
+  return (props.pins ?? []).flatMap((pin) => {
+    const box = onePerPlace(props.rects[pin.path] ?? undefined)[0];
+    if (!box) {
+      return [];
+    }
+    return [
+      <button
+        key={pin.id}
+        className="feedback-pin"
+        title={pin.note}
+        style={{ left: box.x * props.scale, top: box.y * props.scale }}
+        onClick={() => props.onSelectPin?.(pin)}
+      >
+        {pin.index}
+      </button>,
+    ];
+  });
+}
+
 function FocusOverlays({
   path,
   rects,
diff --git a/src/features/preview/PreviewPane.tsx b/src/features/preview/PreviewPane.tsx
index a7cb700b..e196f406 100644
--- a/src/features/preview/PreviewPane.tsx
+++ b/src/features/preview/PreviewPane.tsx
@@ -3,7 +3,7 @@ import { usePreviewSource } from './usePreviewSource';
 import { usePreviewDimensions, usePreviewSizing } from './usePreviewSizing';
 import CanvasView from './CanvasView';
 import type { DevDiagnosis } from './DevOffline';
-import type { OverlayInfo, SpacingHover } from './PreviewOverlays';
+import type { OverlayInfo, PinOverlay, SpacingHover } from './PreviewOverlays';
 import type { PreviewCrumb, PreviewDevice } from './PreviewToolbar';
 import { DevOffline } from './DevOffline';
 import { PreviewOverlays } from './PreviewOverlays';
@@ -40,6 +40,8 @@ interface PreviewPaneProps {
   readonly navigatorSelectionTick?: number;
   readonly navHoverPath?: string | undefined;
   readonly overlayInfo?: (path: string) => OverlayInfo | undefined;
+  readonly pins?: readonly PinOverlay[];
+  readonly onSelectPin?: (pin: PinOverlay) => void;
   readonly onSelectPath?: (path: string | undefined, info: { readonly outside: boolean }) => void;
   readonly onContextPath?: NonNullable<PreviewRuntimeProps['onContextPath']>;
   readonly onOpenPath?: (path: string | undefined, occurrence: number) => void;
@@ -193,34 +195,55 @@ function DesignPreview({
         </div>
         <ResizeHandles sizing={sizing} />
       </div>
-      <div
-        className={`preview-overlay-layer ${width ? '' : 'full'}`}
-        style={{
-          width: sizing.viewport.width * scale,
-          height: sizing.viewport.height * scale,
-          borderRadius: width ? 10 * scale : 0,
-        }}
-      >
-        {/* First in the layer, so the outlines and spacing bands paint over it. */}
-        {shownGuide && <GuideOverlay {...shownGuide} scale={scale} />}
-        <PreviewOverlays
-          rects={runtime.rects}
-          spacing={runtime.spacing}
-          scale={scale}
-          {...(props.spacingHover === undefined ? {} : { spacingHover: props.spacingHover })}
-          selPath={props.selPath}
-          selOcc={runtime.selOcc}
-          hoverPath={runtime.hoverPath}
-          hoverOcc={runtime.hoverOcc}
-          focusPath={props.focusPath}
-          focusWhole={props.focusWhole ?? false}
-          {...(props.overlayInfo === undefined ? {} : { overlayInfo: props.overlayInfo })}
-        />
-      </div>
+      <OverlayLayer props={props} runtime={runtime} sizing={sizing} shownGuide={shownGuide} />
     </>
   );
 }
 
+// The outlines, spacing bands, guide and pins, in screen coordinates over the scaled frame.
+function OverlayLayer({
+  props,
+  runtime,
+  sizing,
+  shownGuide,
+}: {
+  readonly props: PreviewPaneProps;
+  readonly runtime: Runtime;
+  readonly sizing: Sizing;
+  readonly shownGuide: ShownGuide | undefined;
+}) {
+  const width = sizing.width;
+  const scale = sizing.viewport.scale;
+  return (
+    <div
+      className={`preview-overlay-layer ${width ? '' : 'full'}`}
+      style={{
+        width: sizing.viewport.width * scale,
+        height: sizing.viewport.height * scale,
+        borderRadius: width ? 10 * scale : 0,
+      }}
+    >
+      {/* First in the layer, so the outlines and spacing bands paint over it. */}
+      {shownGuide && <GuideOverlay {...shownGuide} scale={scale} />}
+      <PreviewOverlays
+        rects={runtime.rects}
+        spacing={runtime.spacing}
+        scale={scale}
+        {...(props.spacingHover === undefined ? {} : { spacingHover: props.spacingHover })}
+        selPath={props.selPath}
+        selOcc={runtime.selOcc}
+        hoverPath={runtime.hoverPath}
+        hoverOcc={runtime.hoverOcc}
+        focusPath={props.focusPath}
+        focusWhole={props.focusWhole ?? false}
+        {...(props.overlayInfo === undefined ? {} : { overlayInfo: props.overlayInfo })}
+        pins={props.pins}
+        onSelectPin={props.onSelectPin}
+      />
+    </div>
+  );
+}
+
 function ResizeHandles({ sizing }: { readonly sizing: Sizing }) {
   return (
     <>
diff --git a/src/features/preview/previewRuntime.ts b/src/features/preview/previewRuntime.ts
index db965985..cc3d7bf4 100644
--- a/src/features/preview/previewRuntime.ts
+++ b/src/features/preview/previewRuntime.ts
@@ -30,6 +30,8 @@ export interface PreviewRuntimeProps {
   readonly navigatorSelectionTick?: number;
   readonly navHoverPath?: string | undefined;
   readonly overlayInfo?: ((path: string) => OverlayInfo | undefined) | undefined;
+  /** Feedback pins: the frame measures only what it tracks. */
+  readonly pins?: readonly { readonly path: string }[] | undefined;
   readonly focusPath?: string | undefined;
   readonly focusOcc?: number | undefined;
   readonly pathScope?: string;
@@ -110,10 +112,7 @@ export function usePreviewRuntime(
   useMessageListener(iframeRef, refs, setters);
   // The frame measures only tracked paths, so both hover sources must use
   // the same active path for measurement requests and outline rendering.
-  const trackPaths = useMemo(
-    () => trackedPaths(props.selPath, hoverPath, props.focusPath, selectedBoxPath, hoverBoxPath),
-    [props.focusPath, hoverPath, hoverBoxPath, props.selPath, selectedBoxPath],
-  );
+  const trackPaths = useTrackPaths(props, [hoverPath, selectedBoxPath, hoverBoxPath]);
   const link = useFrameLink(iframeRef);
   const registerFrame = useCallback((): void => {
     const frame = iframeRef.current?.contentWindow;
@@ -536,6 +535,28 @@ function useResetOnReload(
   }, [canvasMode, props.refreshKey, refs, setters, url]);
 }
 
+// The paths the frame measures: the selection, the hover, the focus, their
+// outline boxes, and the Feedback pins.
+function useTrackPaths(
+  props: PreviewRuntimeProps,
+  [hoverPath, selectedBoxPath, hoverBoxPath]: readonly (string | undefined)[],
+): readonly string[] {
+  const pinPaths = props.pins?.map((pin) => pin.path).join('\n') ?? '';
+  const { focusPath, selPath: selectionPath } = props;
+  return useMemo(
+    () =>
+      trackedPaths(
+        selectionPath,
+        hoverPath,
+        focusPath,
+        selectedBoxPath,
+        hoverBoxPath,
+        ...pinPaths.split('\n'),
+      ),
+    [focusPath, hoverPath, hoverBoxPath, selectionPath, selectedBoxPath, pinPaths],
+  );
+}
+
 function trackedPaths(...paths: readonly (string | undefined)[]): readonly string[] {
   return [...new Set(paths.filter((path): path is string => Boolean(path)))];
 }
diff --git a/src/features/preview/previewViewport.css b/src/features/preview/previewViewport.css
index afbc9e1f..750ba11b 100644
--- a/src/features/preview/previewViewport.css
+++ b/src/features/preview/previewViewport.css
@@ -66,3 +66,21 @@
 .preview-overlay-layer.full {
   top: 0;
 }
+
+/* A Feedback note's number at its node's top-left corner. The overlay layer
+   lets clicks through to the frame; a pin takes its own. */
+.feedback-pin {
+  position: absolute;
+  width: 18px;
+  height: 18px;
+  transform: translate(-50%, -50%);
+  border-radius: 9px;
+  background: var(--amber);
+  color: #111111;
+  font-size: 10.5px;
+  font-weight: 700;
+  line-height: 18px;
+  text-align: center;
+  pointer-events: auto;
+  cursor: pointer;
+}
diff --git a/studio/scripts/shared-source.json b/studio/scripts/shared-source.json
index c8cdc152..7c142e90 100644
--- a/studio/scripts/shared-source.json
+++ b/studio/scripts/shared-source.json
@@ -112,6 +112,7 @@
     "shared/engine/rebase.ts",
     "shared/engine/splice.ts",
     "shared/ipc/assetConversion.ts",
+    "shared/ipc/feedback.ts",
     "shared/ipc/gitCommitDiff.ts",
     "shared/ipc/githubRepository.ts",
     "shared/ipc/ipcContract.ts",
diff --git a/test/electron/app/mainBoundaries.test.ts b/test/electron/app/mainBoundaries.test.ts
index 4e35900a..fea688c8 100644
--- a/test/electron/app/mainBoundaries.test.ts
+++ b/test/electron/app/mainBoundaries.test.ts
@@ -58,8 +58,9 @@ test('the complete channel inventory matches real main and terminal registration
   );
   // Step 8 retired page:writeRaw; step 9 added page:previewEdit; step 10
   // retired page:write and page:serialize, the Markdown whole-model save.
-  // Publishing, shared project settings, defaults canvases, and history add scoped handlers.
-  assert.equal(harness.handlers.size, 132);
+  // Publishing, shared project settings, defaults canvases, and history add scoped handlers;
+  // the Feedback panel added feedback:read and feedback:write.
+  assert.equal(harness.handlers.size, 134);
   assert.equal(terminalChannels.length, 4);
   assert.deepEqual(
     [...Object.keys(IPC_PAYLOADS)].sort(),
diff --git a/test/electron/handlers/feedbackHandlers.test.ts b/test/electron/handlers/feedbackHandlers.test.ts
new file mode 100644
index 00000000..13bff149
--- /dev/null
+++ b/test/electron/handlers/feedbackHandlers.test.ts
@@ -0,0 +1,51 @@
+// Goal: the Feedback file round-trips through the real main handlers, each
+// item carrying a trail resolved from disk, and a malformed file is refused.
+// Methodology: register main in a windowless VM over a temporary project, write
+// two items (one on a live node, one on a dead key) through the document actor,
+// read them back, then corrupt the file and check the read throws.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { mainHarness } from '../../helpers/mainHarness.ts';
+import { toRecord } from '#dist/shared/core/record.js';
+
+const item = (id: string, key: string) => ({
+  id,
+  keys: [key],
+  label: 'h1',
+  note: `Note ${id}`,
+  createdAt: '2026-10-20T10:31:00Z',
+  done: false,
+});
+
+test('feedback writes resolve trails, create .stacki/, and read back', async (context) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'stacki-feedback-'));
+  fs.mkdirSync(path.join(root, 'src/pages'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'user'));
+  fs.writeFileSync(path.join(root, 'package.json'), '{"dependencies":{"astro":"*"}}');
+  fs.writeFileSync(path.join(root, 'src/pages/index.astro'), '<main>\n  <h1>Hi</h1>\n</main>\n');
+  const harness = mainHarness(path.join(root, 'user'));
+  context.after(() => {
+    harness.dispose();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+  await harness.invoke('project:scan', root);
+
+  const items = [item('live', 'src/pages/index.astro#0'), item('dead', 'src/pages/index.astro#9')];
+  const written = toRecord(await harness.invoke('feedback:write', { projectPath: root, items }));
+  const file = path.join(root, '.stacki/feedback.json');
+  assert.ok(fs.existsSync(file), 'the write created .stacki/feedback.json');
+  const read = toRecord(await harness.invoke('feedback:read', { projectPath: root }));
+  assert.deepEqual(read, written, 'a read returns what the write did');
+  const trails = (Array.isArray(read?.['items']) ? read['items'] : []).map(
+    (entry: unknown) => toRecord(entry)?.['trail'],
+  );
+  assert.deepEqual(trails, [['src/pages/index.astro:1-3'], ['src/pages/index.astro']]);
+
+  fs.writeFileSync(file, '{"version":2,"items":[]}');
+  await assert.rejects(harness.invoke('feedback:read', { projectPath: root }), /version 1/);
+  fs.rmSync(file);
+  assert.deepEqual(await harness.invoke('feedback:read', { projectPath: root }), { items: [] });
+});
diff --git a/test/renderer/feedback/feedback.test.js b/test/renderer/feedback/feedback.test.js
new file mode 100644
index 00000000..15914df1
--- /dev/null
+++ b/test/renderer/feedback/feedback.test.js
@@ -0,0 +1,67 @@
+// Goal: the Feedback panel trusts only parsed replies, hands the agent the open
+// items in order, and pins a note only where its node is on the canvas.
+// Methodology: parse a good reply and one missing `done`; render the handoff
+// for a mix of open and done items; then run the pin rule against the three
+// cases that decide it (same page, drilled into a component, another page).
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const loadRenderer = require('../../helpers/rendererModule');
+
+const bridge = loadRenderer('src/features/feedback/feedbackBridge.ts');
+const { feedbackPins } = loadRenderer('src/features/feedback/feedbackState.ts');
+
+const item = (id, keys, trail, done = false) => ({
+  id,
+  keys,
+  label: 'h1',
+  note: `Note ${id}`,
+  done,
+  trail,
+});
+
+test('replies parse completely or not at all', () => {
+  const good = item('a', ['src/pages/index.astro#0'], ['src/pages/index.astro:1-3']);
+  assert.deepEqual(bridge.parseFeedbackReply({ items: [good] }), [good]);
+  const { done: _done, ...missingDone } = good;
+  assert.throws(() => bridge.parseFeedbackReply({ items: [missingDone] }), /Expected boolean/);
+  assert.throws(() => bridge.parseFeedbackReply({ items: [{ ...good, trail: [1] }] }), /string/);
+});
+
+test('the handoff numbers open items only and joins a trail with ›', () => {
+  const text = bridge.renderHandoff([
+    item('a', [], ['src/pages/index.astro:12-18']),
+    item('b', [], ['src/pages/index.astro:30'], true),
+    item('c', [], ['src/pages/index.astro:31-33', 'src/components/Hero.astro:9-14']),
+    item('d', [], []),
+  ]);
+  const lines = text.split('\n');
+  assert.match(lines[0], /^Address the open items in \.stacki\/feedback\.json \(3 open\)\./);
+  assert.deepEqual(lines.slice(2), [
+    '1. src/pages/index.astro:12-18 (h1): Note a',
+    '2. src/pages/index.astro:31-33 › src/components/Hero.astro:9-14 (h1): Note c',
+    '3. (no source location) (h1): Note d',
+  ]);
+});
+
+test('a note pins only at its own level of the editing stack', () => {
+  const page = 'src/pages/index.astro';
+  const host = `${page}#0.4`;
+  const items = [
+    item('onPage', [`${page}#0.2.1`], []),
+    item('inHero', [host, 'src/components/Hero.astro#1.0'], []),
+    item('otherPage', ['src/pages/about.astro#0'], []),
+    item('pageNote', [`${page}#`], []),
+    item('done', [`${page}#0`], [], true),
+  ];
+  assert.deepEqual(feedbackPins(items, { selectionKeys: [`${page}#0`], editedRel: undefined }), [
+    { id: 'onPage', path: '0.2.1', index: 1, note: 'Note onPage' },
+  ]);
+  const drilled = {
+    selectionKeys: [host, 'src/components/Hero.astro#'],
+    editedRel: 'src/components/Hero.astro',
+  };
+  assert.deepEqual(feedbackPins(items, drilled), [
+    { id: 'inHero', path: 'src/components/Hero.astro|1.0', index: 2, note: 'Note inHero' },
+  ]);
+  assert.deepEqual(feedbackPins(items, { selectionKeys: [], editedRel: undefined }), []);
+});
diff --git a/test/renderer/preview/pinOverlays.test.js b/test/renderer/preview/pinOverlays.test.js
new file mode 100644
index 00000000..cb361bf0
--- /dev/null
+++ b/test/renderer/preview/pinOverlays.test.js
@@ -0,0 +1,50 @@
+// Goal: a Feedback pin draws at its node's first box, scaled like the outlines,
+// and draws nothing when the frame reported no box for it.
+// Methodology: render the overlay layer to static markup with one measured pin
+// and one unmeasured pin, then read the pins back out of the markup.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildSync } = require('esbuild');
+const { repoPath } = require('../../helpers/sources.js');
+
+test('pins draw where their node has a box', () => {
+  const output = repoPath('node_modules/.stacki-test/pin-overlays.cjs');
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  buildSync({
+    entryPoints: [repoPath('src/features/preview/PreviewOverlays.tsx')],
+    outfile: output,
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    jsx: 'automatic',
+    external: ['react', 'react-dom', 'react/jsx-runtime'],
+    logLevel: 'silent',
+  });
+  const React = require('react');
+  const { renderToStaticMarkup } = require('react-dom/server');
+  const { PreviewOverlays } = require(output);
+  const markup = renderToStaticMarkup(
+    React.createElement(PreviewOverlays, {
+      rects: { 0.2: [{ x: 10, y: 20, w: 100, h: 40 }] },
+      spacing: {},
+      scale: 0.5,
+      selPath: undefined,
+      selOcc: undefined,
+      hoverPath: undefined,
+      hoverOcc: undefined,
+      focusPath: undefined,
+      focusWhole: false,
+      pins: [
+        { id: 'a', path: '0.2', index: 1, note: 'Measured' },
+        { id: 'b', path: '0.9', index: 2, note: 'Not rendered' },
+      ],
+    }),
+  );
+  const pins = [...markup.matchAll(/<button class="feedback-pin"[^>]*>(\d+)<\/button>/g)];
+  assert.equal(pins.length, 1, markup);
+  assert.equal(pins[0][1], '1');
+  assert.match(pins[0][0], /title="Measured"/);
+  assert.match(pins[0][0], /left:5px;top:10px/);
+});
diff --git a/test/shared/ipc/feedback.test.ts b/test/shared/ipc/feedback.test.ts
new file mode 100644
index 00000000..135f5f74
--- /dev/null
+++ b/test/shared/ipc/feedback.test.ts
@@ -0,0 +1,28 @@
+// Goal: the Feedback file parser accepts what Stacki and an agent write and
+// refuses what would corrupt the list. Methodology: one known-good file (with an
+// agent-appended item that has no keys or createdAt), then each known-bad shape.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { parseFeedbackFile } from '#dist/shared/ipc/feedback.js';
+
+const item = { id: 'a', keys: ['src/pages/index.astro#0'], label: 'h1', note: 'Fix', done: false };
+const agentItem = { id: 'q', keys: [], label: 'Question', note: 'Which font?', done: false };
+
+test('a valid file parses, ignoring the trail main owns', () => {
+  const parsed = parseFeedbackFile({
+    version: 1,
+    items: [{ ...item, trail: ['src/pages/index.astro:1-3'] }, agentItem],
+  });
+  assert.deepEqual(parsed, { version: 1, items: [item, agentItem] });
+});
+
+test('malformed files are refused', () => {
+  assert.throws(() => parseFeedbackFile({ version: 2, items: [] }), /version 1/);
+  assert.throws(() => parseFeedbackFile({ version: 1 }), /Expected array/);
+  assert.throws(() => parseFeedbackFile({ version: 1, items: [item, item] }), /duplicate item id/);
+  assert.throws(
+    () => parseFeedbackFile({ version: 1, items: [{ ...item, done: undefined }] }),
+    /Expected boolean/,
+  );
+  assert.throws(() => parseFeedbackFile([]), /Expected object/);
+});
diff --git a/test/shared/ipc/ipcPayloads.test.ts b/test/shared/ipc/ipcPayloads.test.ts
index 4a1871d9..b0038635 100644
--- a/test/shared/ipc/ipcPayloads.test.ts
+++ b/test/shared/ipc/ipcPayloads.test.ts
@@ -119,6 +119,16 @@ const fields = {
     stamps: [{ file: 'src/pages/index.astro', checksum: 'b'.repeat(64) }],
   },
   keys: ['src/pages/index.astro#0'],
+  items: [
+    {
+      id: 'k7f3q2',
+      keys: ['src/pages/index.astro#0.2'],
+      label: 'Button',
+      note: 'Full width under 768px',
+      createdAt: '2026-10-20T10:31:00Z',
+      done: false,
+    },
+  ],
   branch: 'feature',
   ref: 'HEAD',
   commit: 'a'.repeat(40),
@@ -248,6 +258,24 @@ test('IPC collection, string, integer, depth, and path bounds fail explicitly',
       }),
     /Array exceeds limit/,
   );
+  const feedback = { projectPath: '/site', items: fields.items };
+  assert.deepEqual(parseIpcPayload('feedback:write', feedback), feedback);
+  assert.throws(
+    () =>
+      parseIpcPayload('feedback:write', {
+        projectPath: '/site',
+        items: Array.from({ length: BOUNDARY_LIMITS.itemsMax + 1 }, () => fields.items[0]),
+      }),
+    /Array exceeds limit/,
+  );
+  assert.throws(
+    () =>
+      parseIpcPayload('feedback:write', {
+        projectPath: '/site',
+        items: [{ ...fields.items[0], done: 'yes' }],
+      }),
+    /Expected boolean/,
+  );
   for (const value of [-1, 1.5, Infinity, Number.MAX_SAFE_INTEGER + 1]) {
     assert.throws(() => parseIpcPayload('git:log', { projectPath: '/site', limit: value }));
   }

From 9a75531c82a1bb0e64096361237aa2c00b09f045 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 11:41:37 +0000
Subject: [PATCH 2/8] feat: annotate the canvas directly in the Feedback tab

With the Feedback tab open, a click on the canvas annotates the element
under the pointer instead of selecting it: a note box opens under the
element, and saved notes show as numbered bubbles pinned to their copy of
the element. A bubble opens a card with the note, Done and Delete. The tab
no longer gives way to the Navigator on a canvas click, because the click
never reaches the selection.

Components are unwrapped: the frame hit-tests every file's markers while
annotating, so an element inside a component is clickable without drilling
in. The click reports the chain of files the element renders through (the
page's instance, each nested instance, then the element), ordered by how
far up the document each file's deepest node reaches, so content a page
slots into its layout still ends on the page. The chain becomes the note's
selection keys, so main resolves the same file:line trail as before, and
the element's marker path and copy index become the note's `marker`, where
its bubble draws.

The agent finds the notes without being told:
- Copy for agent names the file by absolute path, so the paste works from
  any directory.
- The first write adds a short "Stacki feedback" section to the project's
  CLAUDE.md (created if missing) and to AGENTS.md if the project keeps one;
  a CLAUDE.md that imports AGENTS.md is left alone.

Feedback now loads only while its tab is open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 electron/handlers/feedbackHandlers.ts         |  46 ++++
 electron/preload/frameQueries.ts              |   1 +
 electron/preload/frameRegions.ts              |   6 +
 electron/preload/frameTargets.ts              | 110 +++++++++-
 shared/ipc/feedback.ts                        |  11 +-
 src/app/shell/AppPanes.tsx                    |  20 +-
 src/app/shell/AppShell.tsx                    |   9 +-
 src/app/state/appComposers.ts                 |   8 +-
 src/features/feedback/FeedbackPanel.tsx       |  50 ++---
 src/features/feedback/feedback.css            |  15 +-
 src/features/feedback/feedbackBridge.ts       |  14 +-
 src/features/feedback/feedbackState.ts        | 182 +++++++++-------
 src/features/preview/PreviewOverlays.tsx      | 197 +++++++++++++++---
 src/features/preview/PreviewPane.tsx          |   9 +-
 src/features/preview/previewMessages.ts       |  19 ++
 src/features/preview/previewRuntime.ts        |  46 ++--
 .../handlers/feedbackHandlers.test.ts         |  34 ++-
 test/helpers/sources.js                       |   1 +
 test/renderer/app/lazyPanels.test.js          |   9 +
 test/renderer/app/viteModules.test.ts         |   6 +-
 test/renderer/feedback/feedback.test.js       |  70 ++++---
 test/renderer/preview/outlines.test.js        |  32 +++
 test/renderer/preview/pinOverlays.test.js     |  46 ++--
 23 files changed, 687 insertions(+), 254 deletions(-)

diff --git a/electron/handlers/feedbackHandlers.ts b/electron/handlers/feedbackHandlers.ts
index 24d6fc65..c729f287 100644
--- a/electron/handlers/feedbackHandlers.ts
+++ b/electron/handlers/feedbackHandlers.ts
@@ -14,11 +14,27 @@ import {
 import { writeProjectText } from '../documents/documentWrites';
 import { selectionTrail } from '../documents/pageRequests';
 import { readJson } from '../lib/mainHelpers';
+import { readSource } from '../lib/mainLimits';
 import { ensureExcluded } from '../preview/previewWorktree';
 import type { MainHost } from './mainHost';
 
 const FEEDBACK_FILE = path.join('.stacki', 'feedback.json');
 
+// What a project's agent instructions say, so an agent started there without
+// the handoff paste still finds the notes. The file name is also the mark that
+// the note is already in.
+const AGENT_NOTE_MARK = '.stacki/feedback.json';
+const AGENT_NOTE = [
+  '## Stacki feedback',
+  '',
+  'Visual feedback left in the Stacki editor is in `.stacki/feedback.json`. Open items',
+  'have `"done": false`. Each item\'s `trail` lists `file:line` pointers relative to this',
+  'folder: the last entry is the element, the earlier ones the page and the component',
+  'instances around it. When an item is addressed, set its `"done"` to `true` and leave',
+  'everything else in the file as it is.',
+  '',
+].join('\n');
+
 export function registerFeedbackHandlers({
   ipcMain,
   assertInProject,
@@ -35,6 +51,7 @@ export function registerFeedbackHandlers({
     const file = assertInProject(path.join(projectPath, FEEDBACK_FILE));
     fs.mkdirSync(path.dirname(file), { recursive: true });
     ensureExcluded(projectPath);
+    ensureAgentNote(projectPath, assertInProject);
     const trailed = withTrails(projectPath, items);
     const text = JSON.stringify({ version: FEEDBACK_FILE_VERSION, items: trailed }, undefined, 2);
     writeProjectText(file, text + '\n');
@@ -59,3 +76,32 @@ export function withTrails(
   );
   return trailed;
 }
+
+// CLAUDE.md is what Claude Code reads, so it gets the note, created when
+// missing; AGENTS.md gets it only when the project keeps one. A CLAUDE.md that
+// imports AGENTS.md already has it from there.
+function ensureAgentNote(projectPath: string, inProject: (file: string) => string): void {
+  const agents = inProject(path.join(projectPath, 'AGENTS.md'));
+  const claude = inProject(path.join(projectPath, 'CLAUDE.md'));
+  const hasAgents = fs.existsSync(agents);
+  if (hasAgents) {
+    appendAgentNote(agents);
+  }
+  const claudeText = fs.existsSync(claude) ? readSource(claude) : '';
+  if (hasAgents) {
+    if (claudeText.includes('@AGENTS.md')) {
+      return;
+    }
+  }
+  appendAgentNote(claude);
+}
+
+function appendAgentNote(file: string): void {
+  const text = fs.existsSync(file) ? readSource(file) : '';
+  if (text.includes(AGENT_NOTE_MARK)) {
+    return;
+  }
+  const separator = text === '' ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+  writeProjectText(file, text + separator + AGENT_NOTE);
+  assert(readSource(file).includes(AGENT_NOTE_MARK), 'The agent note is in the file');
+}
diff --git a/electron/preload/frameQueries.ts b/electron/preload/frameQueries.ts
index ac34604b..c4a69e0f 100644
--- a/electron/preload/frameQueries.ts
+++ b/electron/preload/frameQueries.ts
@@ -360,6 +360,7 @@ const track = (data: Record<string, unknown>, paths: unknown[]) => {
     scope: typeof data['scope'] === 'string' ? data['scope'] : '',
     focus: typeof data['focus'] === 'string' ? data['focus'] : '',
     occurrence: typeof data['focusOcc'] === 'number' ? data['focusOcc'] : 0,
+    annotating: data['annotate'] === true,
   });
   resetFocusCache();
   resetThinCache(); // scope decides what's hit-testable
diff --git a/electron/preload/frameRegions.ts b/electron/preload/frameRegions.ts
index 4349ea09..88a42737 100644
--- a/electron/preload/frameRegions.ts
+++ b/electron/preload/frameRegions.ts
@@ -43,6 +43,9 @@ export const inScope = (nodePath: string) =>
 // page. Its siblings stay as dim and as unclickable as the rest of it.
 export let focusPath = '';
 export let focusOcc = 0;
+// The Feedback tab is open: a click annotates whatever element is under the
+// pointer, in any file, instead of selecting within the open one.
+export let annotating = false;
 // A run whose every node has left the document isn't an instance any more:
 // a patched page collects fresh runs and leaves the old ones in the map.
 const isLive = (run: Node[]) => run.some((node) => node.isConnected);
@@ -65,11 +68,14 @@ export function setTracking(next: {
   readonly scope: string;
   readonly focus: string;
   readonly occurrence: number;
+  /** Absent from callers that never annotate, such as Stacki Studio's client. */
+  readonly annotating?: boolean;
 }): void {
   trackedPaths = next.paths;
   activeScope = next.scope;
   focusPath = next.focus;
   focusOcc = next.occurrence;
+  annotating = next.annotating ?? false;
 }
 export const focusRoots = (): Node[] | undefined => {
   if (focusCache !== undefined) {
diff --git a/electron/preload/frameTargets.ts b/electron/preload/frameTargets.ts
index af9d3402..cf8239b8 100644
--- a/electron/preload/frameTargets.ts
+++ b/electron/preload/frameTargets.ts
@@ -2,9 +2,10 @@
 // tagged elements and the widened thin targets, and the hover, click and
 // double-click the canvas turns into selection.
 
-import { isElement } from './frameBasics';
+import { PRELOAD_LIMITS, isElement } from './frameBasics';
 import {
   PATH_ATTR,
+  annotating,
   announceMapped,
   collectRegions,
   inFocus,
@@ -174,11 +175,101 @@ const targetAt = (event: MouseEvent): Node | undefined =>
     : undefined) || (event.target instanceof window.Node ? event.target : undefined);
 
 // Same resolution for hover, click and dblclick, so what lights up under the
-// cursor is exactly what a click selects.
-const nodeAtEvent = (event: MouseEvent) =>
-  event.clientX || event.clientY
+// cursor is exactly what a click selects. While annotating, the hover is the
+// element a click would annotate.
+const nodeAtEvent = (event: MouseEvent) => {
+  if (annotating) {
+    const annotation = annotationAt(event);
+    return { path: annotation?.path, occurrence: annotation?.occurrence ?? 0, outside: false };
+  }
+  return event.clientX || event.clientY
     ? nodeAt(targetAt(event), event.clientX, event.clientY)
     : nodeAt(targetAt(event));
+};
+
+// --- Annotating (the Feedback tab) -----------------------------------------
+// Every element is reachable without drilling in: the deepest tagged element
+// under the pointer, whatever file rendered it, with the chain of files it
+// renders through — the page, each component instance, then the element.
+
+interface AnnotationStep {
+  /** The project-relative component file, or '' for the page. */
+  readonly file: string;
+  readonly path: string;
+}
+
+const annotationAt = (event: MouseEvent) => {
+  const target = targetAt(event);
+  let tagged =
+    target instanceof Element ? (target.closest(`[${PATH_ATTR}]`) ?? undefined) : undefined;
+  // A synthesised event with no coordinates keeps its target, as nodeAtEvent does.
+  const located = event.clientX || event.clientY;
+  const x = located ? event.clientX : undefined;
+  const y = located ? event.clientY : undefined;
+  while (tagged && !holdsPoint(tagged, x, y)) {
+    tagged = taggedAncestor(tagged);
+  }
+  const chain = tagged ? annotationChain(tagged) : [];
+  const leaf = chain.at(-1);
+  if (!tagged || !leaf) {
+    return undefined;
+  }
+  const path = leaf.file ? `${leaf.file}|${leaf.path}` : leaf.path;
+  return { path, occurrence: occurrenceOf(path, tagged), chain, label: labelOf(tagged) };
+};
+
+// Each file the element renders through has a deepest node around it: the
+// nearest tagged ancestor-or-self carrying one of that file's paths, its
+// deepest path there. The file whose node wraps the element most tightly is
+// the element itself; the others are outer, by how far up the document their
+// node still reaches. So a page's section slotted into a layout ends on the
+// page (the layout's slot reaches higher), and an element inside a component
+// ends on the component (its instance on the page reaches higher). Ties —
+// a component's root, which carries its instance's page path — put the page first.
+const annotationChain = (element: Element): AnnotationStep[] => {
+  const nearest = new Map<string, string>(); // file → that deepest marker path
+  const reach = new Map<string, number>(); // marker path → highest level carrying it
+  let at: Element | undefined = element;
+  for (let level = 0; at && level < PRELOAD_LIMITS.domDepthMax; level++) {
+    const here = new Map<string, string>();
+    for (const nodePath of pathsOf(at)) {
+      const file = fileOf(nodePath);
+      const had = here.get(file);
+      if (!nearest.has(file) && (had === undefined || depthOf(nodePath) > depthOf(had))) {
+        here.set(file, nodePath);
+      }
+      reach.set(nodePath, level);
+    }
+    for (const [file, nodePath] of here) {
+      nearest.set(file, nodePath);
+    }
+    at = taggedAncestor(at);
+  }
+  const steps = [...nearest].map(([file, nodePath]) => ({
+    file,
+    path: file ? nodePath.slice(file.length + 1) : nodePath,
+    reach: reach.get(nodePath) ?? 0,
+  }));
+  steps.sort(
+    (outer, inner) => inner.reach - outer.reach || pageFirst(outer.file) - pageFirst(inner.file),
+  );
+  return steps.map(({ file, path }) => ({ file, path }));
+};
+
+const depthOf = (nodePath: string): number => nodePath.split('.').length;
+const pageFirst = (file: string): number => (file === '' ? 0 : 1);
+
+const fileOf = (nodePath: string): string => {
+  const bar = nodePath.indexOf('|');
+  return bar === -1 ? '' : nodePath.slice(0, bar);
+};
+
+// What the note's row calls the element: its tag and first class, `div.hero`.
+const labelOf = (element: Element): string => {
+  const first = element.classList[0];
+  const tag = element.tagName.toLowerCase();
+  return first ? `${tag}.${first}` : tag;
+};
 
 export const startOutlines = () => {
   // A page edit now patches the document instead of reloading it, so the
@@ -287,6 +378,10 @@ const listenForPointer = () => {
       }
       event.preventDefault();
       event.stopPropagation();
+      // Annotating reaches inside components already: nothing to open.
+      if (annotating) {
+        return;
+      }
       // Report even when nothing in scope matched: markup the layout renders
       // itself (nav, footer — anything outside the page's <slot>) has no
       // in-scope marker, and the app opens the layout for those.
@@ -310,6 +405,13 @@ const listenForPointer = () => {
       }
       event.preventDefault();
       event.stopPropagation();
+      if (annotating) {
+        const annotation = annotationAt(event);
+        if (annotation) {
+          postLocated('avb:annotate-node', annotation);
+        }
+        return;
+      }
       // A click that hits no marked node still reports (no path), with
       // `outside` saying whether it landed on something the open file simply
       // doesn't own — which is what the app backs out of a component on.
diff --git a/shared/ipc/feedback.ts b/shared/ipc/feedback.ts
index aa5412c0..9cd5e2b7 100644
--- a/shared/ipc/feedback.ts
+++ b/shared/ipc/feedback.ts
@@ -2,17 +2,20 @@
 // pinned to canvas selections, read and edited by Stacki and by a coding agent
 // alike. The file is the whole interface; nothing listens on a port.
 import { assert } from '../core/assert';
-import { boolean, list, object, optional, record, text } from '../core/boundary';
+import { boolean, count, list, object, optional, record, text } from '../core/boundary';
 import type { Parsed } from '../core/boundary';
 
 export const FEEDBACK_FILE_VERSION = 1;
 
-// `keys` are selection keys (`<file>#<index path>`: the page, each drilled-in
-// host, then the leaf). An agent may append its own items with `keys: []`, so
-// `createdAt` is optional for them; the trail is main's to resolve, never read.
+// `keys` are selection keys (`<file>#<index path>`: the page, each component
+// instance the element renders through, then the element). `marker` is where
+// the canvas draws the note's pin: the element's marker path and which copy of
+// it was clicked. An agent may append its own items with `keys: []` and no
+// marker or `createdAt`; the trail is main's to resolve, never read.
 export const parseFeedbackItem = object({
   id: text,
   keys: list(text),
+  marker: optional(object({ path: text, occurrence: count })),
   label: text,
   note: text,
   createdAt: optional(text),
diff --git a/src/app/shell/AppPanes.tsx b/src/app/shell/AppPanes.tsx
index 228e0824..55c76561 100644
--- a/src/app/shell/AppPanes.tsx
+++ b/src/app/shell/AppPanes.tsx
@@ -12,6 +12,7 @@ import type { Attr } from '../../../shared/page/pageNode';
 import { noteText } from '../../editor/treeSelection';
 import { canvasClickAction } from '../../editor/canvasClick';
 import PreviewPane from '../../features/preview/PreviewPane';
+import type { CanvasFeedback } from '../../features/preview/PreviewOverlays';
 import { relativeTime } from '../../features/history/HistoryPanel';
 import SaveConflictNotice from '../SaveConflictNotice';
 import { nodeAtPath } from '../../editor/editorTree';
@@ -59,8 +60,7 @@ export function CanvasPane({ app }: { readonly app: ShellView }) {
         navigatorSelectionTick={app.navigatorSelectionTick}
         navHoverPath={app.pathFor(hoverNodeId)}
         overlayInfo={app.overlayInfo}
-        pins={app.feedback.pins}
-        onSelectPin={(pin) => selectCanvasPath(app, pin.path, { outside: false })}
+        feedback={app.leftTab === 'feedback' ? canvasFeedback(app) : undefined}
         focusPath={app.focusPath}
         focusOcc={app.focusOcc}
         focusWhole={app.focusWhole}
@@ -146,6 +146,22 @@ function canvasContextPosition(
   return { ...point, nodeId: node.id };
 }
 
+// The Feedback tab's hold on the canvas: clicks annotate, pins open notes.
+function canvasFeedback(app: ShellView): CanvasFeedback {
+  const { feedback } = app;
+  return {
+    pins: feedback.pins,
+    openPinId: feedback.openPinId,
+    composer: feedback.composer,
+    onAnnotate: feedback.compose,
+    onAdd: (note) => void feedback.add(note),
+    onCancel: feedback.cancel,
+    onOpenPin: feedback.setOpenPinId,
+    onDone: (id) => void feedback.toggleDone(id),
+    onRemove: (id) => void feedback.remove(id),
+  };
+}
+
 // What a click on the canvas MEANT — see canvasClick.js. The canvas answers with a
 // path or with nothing, and nothing has two causes that want opposite things: a click
 // the open file doesn't own, and a click on something inside it the canvas couldn't
diff --git a/src/app/shell/AppShell.tsx b/src/app/shell/AppShell.tsx
index 6d1c059b..58f592a3 100644
--- a/src/app/shell/AppShell.tsx
+++ b/src/app/shell/AppShell.tsx
@@ -42,7 +42,6 @@ import {
   CodeWindowHost,
   ConflictNotice,
   BusyOverlay,
-  selectCanvasPath,
 } from './AppPanes';
 import type { AppView, ShellView } from '../App';
 
@@ -528,13 +527,7 @@ export function FeedbackTab({ app }: { readonly app: ShellView }) {
   return (
     <FeedbackPanel
       feedback={app.feedback}
-      target={app.overlayInfo(app.pathFor(app.selectedId) ?? '')?.label}
-      selectedKey={app.selectionKeysRef.current.at(-1)}
-      onSelectPin={(pin) => {
-        selectCanvasPath(app, pin.path, { outside: false });
-        // Selecting reveals the node in the Navigator; a note's row keeps its panel.
-        app.setLeftTab('feedback');
-      }}
+      projectPath={app.project.path}
       showToast={app.showToast}
     />
   );
diff --git a/src/app/state/appComposers.ts b/src/app/state/appComposers.ts
index f3ffcbfb..e6ddf361 100644
--- a/src/app/state/appComposers.ts
+++ b/src/app/state/appComposers.ts
@@ -46,12 +46,12 @@ export function useAppScope() {
   const propertyEdits = usePropertyEdits(coreState, lifecycle, history, nodeEdits);
   const pageOps = usePageOps(coreState, lifecycle, navigation, history, nodeEdits, shortcuts);
   const viewModel = useViewModel(coreState, lifecycle, shortcuts, pageOps);
-  // After the view model: it sets the selection keys this render pins notes to.
+  // After the view model: it sets the selection keys, whose first names the page.
+  const pageKey = coreState.selectionKeysRef.current[0];
   const feedback = useFeedback({
     projectPath: coreState.project?.path,
-    selectionKeys: coreState.selectionKeysRef.current,
-    editedRel: viewModel.editedRel,
-    label: viewModel.overlayInfo(viewModel.pathFor(coreState.selectedId) ?? '')?.label,
+    active: coreState.leftTab === 'feedback',
+    pageRel: pageKey === undefined ? undefined : pageKey.slice(0, pageKey.indexOf('#')),
     showToast: lifecycle.showToast,
   });
   return {
diff --git a/src/features/feedback/FeedbackPanel.tsx b/src/features/feedback/FeedbackPanel.tsx
index 8d78fe0b..ade4d4bb 100644
--- a/src/features/feedback/FeedbackPanel.tsx
+++ b/src/features/feedback/FeedbackPanel.tsx
@@ -1,46 +1,25 @@
-import React, { useEffect, useState } from 'react';
-import type { KeyboardEvent } from 'react';
+import React from 'react';
 import type { TrailedFeedbackItem } from '../../../shared/ipc/feedback';
 import { CheckIcon, CloseIcon } from '../../ui/Icons';
 import { renderHandoff } from './feedbackBridge';
-import type { FeedbackPin, useFeedback } from './feedbackState';
+import type { useFeedback } from './feedbackState';
 import './feedback.css';
 
 interface FeedbackPanelProps {
   readonly feedback: ReturnType<typeof useFeedback>['feedback'];
-  /** What a new note attaches to: the selected node's name, or the page. */
-  readonly target: string | undefined;
-  /** The current selection's leaf key; its rows are highlighted. */
-  readonly selectedKey: string | undefined;
-  readonly onSelectPin: (pin: FeedbackPin) => void;
+  readonly projectPath: string;
   readonly showToast: (message: string, kind: 'success' | 'error') => void;
 }
 
-// Notes pinned to canvas selections, kept in .stacki/feedback.json for a coding
-// agent: select an element, type, press Enter; Copy for agent hands them over.
+// The notes left on the canvas, kept in .stacki/feedback.json for a coding
+// agent: click an element and type; Copy for agent hands them over.
 export default function FeedbackPanel(props: FeedbackPanelProps) {
   const { feedback } = props;
-  const [draft, setDraft] = useState('');
-  const { reload } = feedback;
-  // Opening the tab catches up with what an agent changed in the file.
-  useEffect(() => void reload(), [reload]);
   const open = feedback.items.filter((item) => !item.done);
   const done = feedback.items.filter((item) => item.done);
-
-  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>): void => {
-    if (event.key !== 'Enter' || event.shiftKey) {
-      return;
-    }
-    event.preventDefault();
-    const note = draft.trim();
-    if (note) {
-      setDraft('');
-      void feedback.add(note);
-    }
-  };
   const copy = async (): Promise<void> => {
     try {
-      await navigator.clipboard.writeText(renderHandoff(feedback.items));
+      await navigator.clipboard.writeText(renderHandoff(feedback.items, props.projectPath));
       props.showToast('Copied. Paste it into Claude Code in the project.', 'success');
     } catch {
       props.showToast('Could not copy the feedback.', 'error');
@@ -55,13 +34,7 @@ export default function FeedbackPanel(props: FeedbackPanelProps) {
         </button>
       </div>
       <div className="panel-body feedback-body">
-        <textarea
-          className="feedback-input"
-          value={draft}
-          placeholder={props.target ? `Note on ${props.target}` : 'Note on this page'}
-          onChange={(event) => setDraft(event.target.value)}
-          onKeyDown={onKeyDown}
-        />
+        <p className="feedback-hint">Click an element on the canvas to leave a note on it.</p>
         {open.map((item, index) => (
           <FeedbackRow key={item.id} item={item} number={index + 1} {...props} />
         ))}
@@ -87,12 +60,13 @@ function FeedbackRow(
   },
 ) {
   const { item, feedback } = props;
-  const pin = feedback.pins.find((candidate) => candidate.id === item.id);
-  const selected = item.keys.at(-1) === props.selectedKey ? ' is-selected' : '';
+  // A row with a pin on this page opens it, so the note shows where it was left.
+  const pinned = feedback.pins.some((pin) => pin.id === item.id);
+  const open = feedback.openPinId === item.id ? ' is-selected' : '';
   return (
     <div
-      className={`feedback-row${item.done ? ' is-done' : ''}${selected}`}
-      onClick={() => pin && props.onSelectPin(pin)}
+      className={`feedback-row${item.done ? ' is-done' : ''}${open}`}
+      onClick={() => pinned && feedback.setOpenPinId(open ? undefined : item.id)}
     >
       <span className="feedback-number">{props.number ?? ''}</span>
       <div className="feedback-main">
diff --git a/src/features/feedback/feedback.css b/src/features/feedback/feedback.css
index f8caa5e3..5bcd20e0 100644
--- a/src/features/feedback/feedback.css
+++ b/src/features/feedback/feedback.css
@@ -2,17 +2,12 @@
 .feedback-body {
   padding: 0 8px 12px;
 }
-.feedback-input {
-  width: 100%;
-  min-height: 52px;
-  resize: vertical;
+.feedback-hint {
   margin-bottom: 8px;
-  padding: 6px 8px;
-  font: 11.5px/1.4 var(--font);
-  color: var(--text);
-  background: var(--bg-input);
-  border: 1px solid var(--border);
-  border-radius: 6px;
+  padding: 0 4px;
+  font-size: 11.5px;
+  line-height: 1.5;
+  color: var(--text-faint);
 }
 .feedback-row {
   display: flex;
diff --git a/src/features/feedback/feedbackBridge.ts b/src/features/feedback/feedbackBridge.ts
index 72e78e93..d78ac6d1 100644
--- a/src/features/feedback/feedbackBridge.ts
+++ b/src/features/feedback/feedbackBridge.ts
@@ -25,18 +25,20 @@ export function writeFeedback(projectPath: string, items: readonly FeedbackItem[
   return feedbackRequest(() => window.avb.writeFeedback(payload));
 }
 
-/** The one paste that starts the agent: the protocol, then each open item. */
-export function renderHandoff(items: readonly TrailedFeedbackItem[]): string {
+/** The one paste that starts the agent: the protocol, then each open item. The
+ * file is named absolutely, so the paste works wherever the agent was started. */
+export function renderHandoff(items: readonly TrailedFeedbackItem[], projectPath: string): string {
   const open = items.filter((item) => !item.done);
   const lines = open.map((item, index) => {
     const where = item.trail.length > 0 ? item.trail.join(' › ') : '(no source location)';
     return `${index + 1}. ${where} (${item.label}): ${item.note}`;
   });
   return [
-    `Address the open items in .stacki/feedback.json (${open.length} open). For each item, ` +
-      'open every file:line in its trail — the last entry is the element, the earlier ones ' +
-      'are the page and the component instances it sits in — make the change, then set ' +
-      'that item\'s "done" to true in the file.',
+    `Address the open items in ${projectPath}/.stacki/feedback.json (${open.length} open). ` +
+      `Trails are relative to ${projectPath}. For each item, open every file:line in its ` +
+      'trail — the last entry is the element, the earlier ones are the page and the ' +
+      'component instances it sits in — make the change, then set that item\'s "done" to ' +
+      'true in the file.',
     '',
     ...lines,
   ].join('\n');
diff --git a/src/features/feedback/feedbackState.ts b/src/features/feedback/feedbackState.ts
index ecd166a4..c3e056ee 100644
--- a/src/features/feedback/feedbackState.ts
+++ b/src/features/feedback/feedbackState.ts
@@ -1,103 +1,142 @@
-// The Feedback list the panel and the canvas share. The file is the only
+// The Feedback notes the panel and the canvas share. The file is the only
 // state: every change reads it fresh, applies the change, and writes it back,
 // so an agent's edits made in the meantime (done flips, its own items) survive.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { assert } from '../../../shared/core/assert';
+import type { Result } from '../../../shared/core/result';
 import type { FeedbackItem, TrailedFeedbackItem } from '../../../shared/ipc/feedback';
 import { readFeedback, writeFeedback } from './feedbackBridge';
 
 export interface FeedbackPin {
   readonly id: string;
-  /** The marker path the canvas frame measures and selects by. */
+  /** The element's marker path, in whichever file rendered it. */
   readonly path: string;
+  readonly occurrence: number;
   /** The item's 1-based number among the open items, as the list shows it. */
   readonly index: number;
   readonly note: string;
 }
 
+/** A click on the canvas while annotating: the element and the files it
+ * renders through, outermost first ('' is the page). */
+export interface FeedbackAnnotation {
+  readonly path: string;
+  readonly occurrence: number;
+  readonly chain: readonly { readonly file: string; readonly path: string }[];
+  readonly label: string;
+}
+
+interface Composing {
+  readonly keys: readonly string[];
+  readonly marker: { readonly path: string; readonly occurrence: number };
+  readonly label: string;
+}
+
 interface FeedbackContext {
   readonly projectPath: string | undefined;
-  /** The current selection keys: each drilled-in host, then the leaf. */
-  readonly selectionKeys: readonly string[];
-  readonly editedRel: string | undefined;
-  /** The selected node's name, for a new note's label. */
-  readonly label: string | undefined;
+  /** Whether the Feedback tab is open: notes load, pin and annotate only then. */
+  readonly active: boolean;
+  /** The open page, project-relative: what a chain's '' file means. */
+  readonly pageRel: string | undefined;
   readonly showToast: (message: string, kind: 'error') => void;
 }
 
 export function useFeedback(context: FeedbackContext) {
-  const { projectPath, selectionKeys, editedRel, label, showToast } = context;
+  const { active, pageRel } = context;
+  const { items, reload, change } = useFeedbackFile(context);
+  const [composing, setComposing] = useState<Composing | undefined>(undefined);
+  const [openPinId, setOpenPinId] = useState<string | undefined>(undefined);
+  const pins = useMemo(
+    () => (active && pageRel ? feedbackPins(items, pageRel) : []),
+    [active, items, pageRel],
+  );
+  const compose = (annotation: FeedbackAnnotation): void => {
+    if (!pageRel) {
+      return;
+    }
+    setOpenPinId(undefined);
+    setComposing({
+      keys: annotation.chain.map((step) => `${step.file || pageRel}#${step.path}`),
+      marker: { path: annotation.path, occurrence: annotation.occurrence },
+      label: annotation.label,
+    });
+  };
+  const add = (note: string): Promise<void> => {
+    if (!composing) {
+      return Promise.resolve();
+    }
+    setComposing(undefined);
+    return change((previous) => [...previous, newItem(composing, note)]);
+  };
+  const toggleDone = (id: string): Promise<void> =>
+    change((previous) =>
+      previous.map((item) => (item.id === id ? { ...item, done: !item.done } : item)),
+    );
+  const remove = (id: string): Promise<void> =>
+    change((previous) => previous.filter((item) => item.id !== id));
+  const clearDone = (): Promise<void> =>
+    change((previous) => previous.filter((item) => !item.done));
+  const composer =
+    active && composing ? { ...composing.marker, target: composing.label } : undefined;
+  const cancel = (): void => setComposing(undefined);
+  const actions = { reload, compose, add, cancel, toggleDone, remove, clearDone };
+  return { feedback: { items, pins, composer, openPinId, setOpenPinId, ...actions } };
+}
+
+// The file's items while the tab is open: read on opening, on window focus, and
+// before every change, which is applied to the fresh read and written back.
+function useFeedbackFile({ projectPath, active, showToast }: FeedbackContext) {
   const [items, setItems] = useState<readonly TrailedFeedbackItem[]>([]);
   // Replies for a project that is no longer open are dropped.
   const projectRef = useRef(projectPath);
   projectRef.current = projectPath;
-
+  const settle = useCallback(
+    (requested: string, result: Result<readonly TrailedFeedbackItem[], string>): void => {
+      if (projectRef.current !== requested) {
+        return;
+      }
+      if (result.ok) {
+        setItems(result.value);
+      } else {
+        showToast(result.error, 'error');
+      }
+    },
+    [showToast],
+  );
   const reload = useCallback(async (): Promise<void> => {
-    const requested = projectPath;
-    if (!requested) {
-      setItems([]);
-      return;
+    if (projectPath) {
+      settle(projectPath, await readFeedback(projectPath));
     }
-    const result = await readFeedback(requested);
-    if (projectRef.current !== requested) {
-      return;
-    }
-    if (result.ok) {
-      setItems(result.value);
-    } else {
-      showToast(result.error, 'error');
-    }
-  }, [projectPath, showToast]);
-
+  }, [projectPath, settle]);
   const change = useCallback(
     async (apply: (items: readonly FeedbackItem[]) => readonly FeedbackItem[]): Promise<void> => {
       if (!projectPath) {
         return;
       }
       const current = await readFeedback(projectPath);
-      const written = current.ok ? await writeFeedback(projectPath, apply(current.value)) : current;
-      if (projectRef.current !== projectPath) {
-        return;
-      }
-      if (written.ok) {
-        setItems(written.value);
-      } else {
-        showToast(written.error, 'error');
-      }
+      const next = current.ok ? await writeFeedback(projectPath, apply(current.value)) : current;
+      settle(projectPath, next);
     },
-    [projectPath, showToast],
+    [projectPath, settle],
   );
-
   useEffect(() => {
-    void reload();
+    if (!active) {
+      return undefined;
+    }
     const onFocus = (): void => void reload();
+    onFocus();
     window.addEventListener('focus', onFocus);
     return () => window.removeEventListener('focus', onFocus);
-  }, [reload]);
-
-  const keysKey = selectionKeys.join('\n');
-  const pins = useMemo(
-    () => feedbackPins(items, { selectionKeys: keysKey.split('\n'), editedRel }),
-    [items, keysKey, editedRel],
-  );
-  const add = (note: string): Promise<void> =>
-    change((previous) => [...previous, newItem(selectionKeys, label ?? 'page', note)]);
-  const toggleDone = (id: string): Promise<void> =>
-    change((previous) =>
-      previous.map((item) => (item.id === id ? { ...item, done: !item.done } : item)),
-    );
-  const remove = (id: string): Promise<void> =>
-    change((previous) => previous.filter((item) => item.id !== id));
-  const clearDone = (): Promise<void> =>
-    change((previous) => previous.filter((item) => !item.done));
-  return { feedback: { items, pins, reload, add, toggleDone, remove, clearDone } };
+  }, [active, reload]);
+  return { items, reload, change };
 }
 
-function newItem(keys: readonly string[], label: string, note: string): FeedbackItem {
+function newItem(composing: Composing, note: string): FeedbackItem {
   return {
     id: crypto.randomUUID().slice(0, 8),
-    keys: [...keys],
-    label,
+    keys: [...composing.keys],
+    marker: composing.marker,
+    label: composing.label,
     note,
     createdAt: new Date().toISOString(),
     done: false,
@@ -105,36 +144,23 @@ function newItem(keys: readonly string[], label: string, note: string): Feedback
 }
 
 /**
- * The open items that draw on the canvas: those pinned at the current level of
- * the editing stack (same drilled-in hosts) to a node of the open file.
- * Everything else stays in the list without a pin.
+ * The open items that draw on the canvas: those left on the open page that
+ * know where they were clicked. Everything else (another page, an agent's own
+ * item) stays in the list without a pin.
  */
 export function feedbackPins(
   items: readonly TrailedFeedbackItem[],
-  at: { readonly selectionKeys: readonly string[]; readonly editedRel: string | undefined },
+  pageRel: string,
 ): readonly FeedbackPin[] {
-  const currentLeaf = at.selectionKeys.at(-1);
-  if (currentLeaf === undefined) {
-    return [];
-  }
-  const currentHosts = at.selectionKeys.slice(0, -1).join('\n');
-  const openFile = currentLeaf.slice(0, currentLeaf.indexOf('#'));
+  const onPage = (key: string): boolean => key.slice(0, key.indexOf('#')) === pageRel;
   const pins: FeedbackPin[] = [];
   items
     .filter((item) => !item.done)
     .forEach((item, position) => {
-      const leaf = item.keys.at(-1);
-      if (leaf === undefined || item.keys.slice(0, -1).join('\n') !== currentHosts) {
-        return;
-      }
-      const hash = leaf.indexOf('#');
-      const indexPath = leaf.slice(hash + 1);
-      // A page-level note (`file#`) or the frontmatter has no box to pin to.
-      if (hash === -1 || leaf.slice(0, hash) !== openFile || !/^\d+(\.\d+)*$/.test(indexPath)) {
-        return;
+      if (item.marker && item.keys.some(onPage)) {
+        const { path, occurrence } = item.marker;
+        pins.push({ id: item.id, path, occurrence, index: position + 1, note: item.note });
       }
-      const path = at.editedRel ? `${at.editedRel}|${indexPath}` : indexPath;
-      pins.push({ id: item.id, path, index: position + 1, note: item.note });
     });
   assert(pins.length <= items.length, 'At most one pin per item');
   return pins;
diff --git a/src/features/preview/PreviewOverlays.tsx b/src/features/preview/PreviewOverlays.tsx
index 87746729..5d02426b 100644
--- a/src/features/preview/PreviewOverlays.tsx
+++ b/src/features/preview/PreviewOverlays.tsx
@@ -1,6 +1,6 @@
-import React from 'react';
+import React, { useState } from 'react';
 import type { Box } from './outlineBoxes';
-import type { PreviewMessage } from './previewMessages';
+import type { Annotation, PreviewMessage } from './previewMessages';
 import { hoverIsSelection, onePerPlace, outlineBoxPath } from './outlineBoxes';
 import { spacingBands, withLiveSpacing } from './spacingBands';
 import {
@@ -28,14 +28,32 @@ export interface OverlayInfo {
   readonly bound: boolean;
 }
 
-/** A Feedback note drawn on the canvas at its node's first box. */
+/** A Feedback note drawn on the canvas, on one copy of its element. */
 export interface PinOverlay {
   readonly id: string;
+  /** The element's marker path, in whichever file rendered it. */
   readonly path: string;
+  readonly occurrence: number;
+  /** The 1-based number the Feedback list shows the note under. */
   readonly index: number;
   readonly note: string;
 }
 
+/** The Feedback tab's layer: clicks annotate, notes show as pins, and a box
+ * takes the note for the element just clicked. */
+export interface CanvasFeedback {
+  readonly pins: readonly PinOverlay[];
+  readonly openPinId: string | undefined;
+  readonly composer:
+    { readonly path: string; readonly occurrence: number; readonly target: string } | undefined;
+  readonly onAnnotate: (annotation: Annotation) => void;
+  readonly onAdd: (note: string) => void;
+  readonly onCancel: () => void;
+  readonly onOpenPin: (id: string | undefined) => void;
+  readonly onDone: (id: string) => void;
+  readonly onRemove: (id: string) => void;
+}
+
 export interface SpacingHover {
   readonly kind: 'padding' | 'margin' | 'gap';
   readonly sides?: readonly string[];
@@ -62,8 +80,7 @@ interface PreviewOverlaysProps {
   readonly focusPath: string | undefined;
   readonly focusWhole: boolean;
   readonly overlayInfo?: (path: string) => OverlayInfo | undefined;
-  readonly pins?: readonly PinOverlay[] | undefined;
-  readonly onSelectPin?: ((pin: PinOverlay) => void) | undefined;
+  readonly feedback?: CanvasFeedback | undefined;
 }
 
 export function PreviewOverlays(props: PreviewOverlaysProps) {
@@ -74,32 +91,13 @@ export function PreviewOverlays(props: PreviewOverlaysProps) {
       )}
       <SpacingOverlays {...props} />
       <NodeOutlines {...props} />
-      <PinOverlays {...props} />
+      {props.feedback && (
+        <FeedbackOverlays feedback={props.feedback} rects={props.rects} scale={props.scale} />
+      )}
     </>
   );
 }
 
-// A pin whose node reported no box (another branch, off the page) draws nothing.
-function PinOverlays(props: PreviewOverlaysProps) {
-  return (props.pins ?? []).flatMap((pin) => {
-    const box = onePerPlace(props.rects[pin.path] ?? undefined)[0];
-    if (!box) {
-      return [];
-    }
-    return [
-      <button
-        key={pin.id}
-        className="feedback-pin"
-        title={pin.note}
-        style={{ left: box.x * props.scale, top: box.y * props.scale }}
-        onClick={() => props.onSelectPin?.(pin)}
-      >
-        {pin.index}
-      </button>,
-    ];
-  });
-}
-
 function FocusOverlays({
   path,
   rects,
@@ -143,7 +141,9 @@ function SpacingOverlays(props: PreviewOverlaysProps) {
 function NodeOutlines(props: PreviewOverlaysProps) {
   const outlines = outlineTargets(props);
   return outlines.flatMap((outline) => {
-    const info = props.overlayInfo?.(outline.path);
+    // An annotation can name an element of any file, which the open file's
+    // model cannot label: outline it plainly.
+    const info = props.feedback ? ANNOTATION_OUTLINE : props.overlayInfo?.(outline.path);
     const geometryPath = outlineBoxPath(outline.path, info?.nodeKind);
     const all = props.rects[geometryPath] ?? props.rects[outline.path];
     if (!all || !info) {
@@ -160,10 +160,12 @@ function NodeOutlines(props: PreviewOverlaysProps) {
         className={`node-outline ${outline.type} ${info.kind}${info.bound ? ' bound' : ''}`}
         style={boxStyle(box, props.scale)}
       >
-        <span className={`node-outline-tag ${box.y * props.scale < 20 ? 'inside' : ''}`}>
-          {outlineIcon(info)}
-          {info.label}
-        </span>
+        {info.label && (
+          <span className={`node-outline-tag ${box.y * props.scale < 20 ? 'inside' : ''}`}>
+            {outlineIcon(info)}
+            {info.label}
+          </span>
+        )}
       </div>
     ));
   });
@@ -186,12 +188,25 @@ function outlineTargets(props: PreviewOverlaysProps): readonly OutlineTarget[] {
   ) {
     targets.push({ path: props.hoverPath, type: 'hover', occ: props.hoverOcc });
   }
-  if (props.selPath) {
+  // While annotating, the note box marks what was clicked; the editor's
+  // selection is not what a click there means.
+  if (props.selPath && !props.feedback) {
     targets.push({ path: props.selPath, type: 'sel', occ: props.selOcc });
   }
   return targets;
 }
 
+const ANNOTATION_OUTLINE: OverlayInfo = {
+  label: '',
+  kind: 'element',
+  tag: undefined,
+  astroAsset: false,
+  dynamicTag: false,
+  nodeKind: 'element',
+  isLayout: false,
+  bound: false,
+};
+
 function outlineIcon(info: OverlayInfo): React.ReactNode {
   const size = 11;
   if (info.isLayout) {
@@ -240,3 +255,119 @@ function spacingLabel(box: Box & { readonly side: string }): string {
   const horizontal = box.side === 'left' || box.side === 'right';
   return `${Math.round(horizontal ? box.w : box.h)}px`;
 }
+
+// The Feedback pins, each opening a card with its note, and the box that takes
+// a new note under the element just clicked. A pin or a box whose element
+// reported no rect (another branch, off the page) draws nothing.
+function FeedbackOverlays({
+  feedback,
+  rects,
+  scale,
+}: {
+  readonly feedback: CanvasFeedback;
+  readonly rects: RectMap;
+  readonly scale: number;
+}) {
+  const boxOf = (place: { readonly path: string; readonly occurrence: number }) => {
+    const all = rects[place.path];
+    return all?.[place.occurrence] ?? all?.[0];
+  };
+  const { composer } = feedback;
+  const composerBox = composer && boxOf(composer);
+  return (
+    <>
+      {feedback.pins.flatMap((pin) => {
+        const box = boxOf(pin);
+        if (!box) {
+          return [];
+        }
+        const open = feedback.openPinId === pin.id;
+        return [
+          <div
+            key={pin.id}
+            style={{ position: 'absolute', left: box.x * scale, top: box.y * scale }}
+          >
+            <button
+              className={`feedback-pin${open ? ' is-open' : ''}`}
+              title={pin.note}
+              onClick={() => feedback.onOpenPin(open ? undefined : pin.id)}
+            >
+              {pin.index}
+            </button>
+            {open && <PinCard pin={pin} feedback={feedback} />}
+          </div>,
+        ];
+      })}
+      {composer && composerBox && (
+        <NoteComposer
+          key={`${composer.path}#${composer.occurrence}`}
+          target={composer.target}
+          left={composerBox.x * scale}
+          top={(composerBox.y + composerBox.h) * scale + 6}
+          feedback={feedback}
+        />
+      )}
+    </>
+  );
+}
+
+function PinCard({
+  pin,
+  feedback,
+}: {
+  readonly pin: PinOverlay;
+  readonly feedback: CanvasFeedback;
+}) {
+  return (
+    <div className="feedback-card">
+      <p className="feedback-card-note">{pin.note}</p>
+      <div className="feedback-card-actions">
+        <button onClick={() => feedback.onDone(pin.id)}>Done</button>
+        <button onClick={() => feedback.onRemove(pin.id)}>Delete</button>
+      </div>
+    </div>
+  );
+}
+
+// Enter adds the note, Shift+Enter breaks the line, Escape closes the box.
+function NoteComposer(props: {
+  readonly target: string;
+  readonly left: number;
+  readonly top: number;
+  readonly feedback: CanvasFeedback;
+}) {
+  const [draft, setDraft] = useState('');
+  const submit = (): void => {
+    const note = draft.trim();
+    if (note) {
+      props.feedback.onAdd(note);
+    }
+  };
+  const onKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>): void => {
+    if (event.key === 'Escape') {
+      // The box's own Escape: the app's (leave the component) must not fire too.
+      event.stopPropagation();
+      props.feedback.onCancel();
+    } else if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  };
+  return (
+    <div className="feedback-card feedback-composer" style={{ left: props.left, top: props.top }}>
+      <textarea
+        autoFocus
+        value={draft}
+        placeholder={`Note on ${props.target}`}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={onKeyDown}
+      />
+      <div className="feedback-card-actions">
+        <button onClick={props.feedback.onCancel}>Cancel</button>
+        <button className="is-primary" disabled={!draft.trim()} onClick={submit}>
+          Add note
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/features/preview/PreviewPane.tsx b/src/features/preview/PreviewPane.tsx
index e196f406..de0880e7 100644
--- a/src/features/preview/PreviewPane.tsx
+++ b/src/features/preview/PreviewPane.tsx
@@ -3,7 +3,7 @@ import { usePreviewSource } from './usePreviewSource';
 import { usePreviewDimensions, usePreviewSizing } from './usePreviewSizing';
 import CanvasView from './CanvasView';
 import type { DevDiagnosis } from './DevOffline';
-import type { OverlayInfo, PinOverlay, SpacingHover } from './PreviewOverlays';
+import type { CanvasFeedback, OverlayInfo, SpacingHover } from './PreviewOverlays';
 import type { PreviewCrumb, PreviewDevice } from './PreviewToolbar';
 import { DevOffline } from './DevOffline';
 import { PreviewOverlays } from './PreviewOverlays';
@@ -40,8 +40,8 @@ interface PreviewPaneProps {
   readonly navigatorSelectionTick?: number;
   readonly navHoverPath?: string | undefined;
   readonly overlayInfo?: (path: string) => OverlayInfo | undefined;
-  readonly pins?: readonly PinOverlay[];
-  readonly onSelectPin?: (pin: PinOverlay) => void;
+  /** Present while the Feedback tab is open: the canvas annotates. */
+  readonly feedback?: CanvasFeedback | undefined;
   readonly onSelectPath?: (path: string | undefined, info: { readonly outside: boolean }) => void;
   readonly onContextPath?: NonNullable<PreviewRuntimeProps['onContextPath']>;
   readonly onOpenPath?: (path: string | undefined, occurrence: number) => void;
@@ -237,8 +237,7 @@ function OverlayLayer({
         focusPath={props.focusPath}
         focusWhole={props.focusWhole ?? false}
         {...(props.overlayInfo === undefined ? {} : { overlayInfo: props.overlayInfo })}
-        pins={props.pins}
-        onSelectPin={props.onSelectPin}
+        feedback={props.feedback}
       />
     </div>
   );
diff --git a/src/features/preview/previewMessages.ts b/src/features/preview/previewMessages.ts
index bf73dc2f..807ad203 100644
--- a/src/features/preview/previewMessages.ts
+++ b/src/features/preview/previewMessages.ts
@@ -7,9 +7,11 @@ import {
   dictionary,
   digest,
   list,
+  object,
   optional,
   pathText,
   record,
+  text,
 } from '../../../shared/core/boundary';
 import type { Digest } from '../../../shared/core/brand';
 import { parsePreviewRender, type PreviewRender } from '../../../shared/page/previewToken';
@@ -37,6 +39,7 @@ export type PreviewMessage =
   | ({ readonly kind: 'click-node'; readonly outside: boolean } & LocatedEvent)
   | ({ readonly kind: 'open-node' } & LocatedEvent)
   | ({ readonly kind: 'context-node'; readonly outside: boolean } & LocatedEvent & ContextPoint)
+  | ({ readonly kind: 'annotate-node' } & Annotation)
   | { readonly kind: 'canvas-ready' }
   /** What the column guide is drawn from (electron/preload/frameGuide.ts). */
   | { readonly kind: 'guide'; readonly metrics: GuideMetrics }
@@ -125,6 +128,14 @@ export interface LocatedEvent {
   readonly token: Digest | undefined;
 }
 
+/** A click while annotating (the Feedback tab): the element under the pointer,
+ * the files it renders through outermost first ('' is the page), and its name. */
+export type Annotation = Omit<LocatedEvent, 'path'> & {
+  readonly path: string;
+  readonly chain: readonly { readonly file: string; readonly path: string }[];
+  readonly label: string;
+};
+
 export function parsePreviewMessage(input: unknown): PreviewMessage | undefined {
   let value: Readonly<Record<string, unknown>>;
   try {
@@ -174,6 +185,14 @@ function parseKnownMessage(value: Readonly<Record<string, unknown>>): PreviewMes
       };
     case 'avb:open-node':
       return { kind: 'open-node', ...parseLocatedMessage(value) };
+    case 'avb:annotate-node':
+      return {
+        kind: 'annotate-node',
+        ...parseLocatedMessage(value),
+        path: pathText(value['path']),
+        chain: list(object({ file: pathText, path: pathText }))(value['chain']),
+        label: text(value['label']),
+      };
     case 'avb:canvas-ready':
       return { kind: 'canvas-ready' };
     case 'avb:guide':
diff --git a/src/features/preview/previewRuntime.ts b/src/features/preview/previewRuntime.ts
index cc3d7bf4..c5e5e033 100644
--- a/src/features/preview/previewRuntime.ts
+++ b/src/features/preview/previewRuntime.ts
@@ -1,7 +1,7 @@
 import { frameContextPoint, type ContextPoint } from './contextPosition';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type React from 'react';
-import type { OverlayInfo, RectMap, SpacingMap } from './PreviewOverlays';
+import type { CanvasFeedback, OverlayInfo, RectMap, SpacingMap } from './PreviewOverlays';
 import type { PreviewDevice } from './PreviewToolbar';
 import type { PreviewMessage, PreviewReloadReason } from './previewMessages';
 import type { GuideMetrics } from './guideModel';
@@ -30,8 +30,9 @@ export interface PreviewRuntimeProps {
   readonly navigatorSelectionTick?: number;
   readonly navHoverPath?: string | undefined;
   readonly overlayInfo?: ((path: string) => OverlayInfo | undefined) | undefined;
-  /** Feedback pins: the frame measures only what it tracks. */
-  readonly pins?: readonly { readonly path: string }[] | undefined;
+  /** The Feedback tab is open: clicks annotate, and the pins and the note box
+   * are measured (the frame measures only what it tracks). */
+  readonly feedback?: CanvasFeedback | undefined;
   readonly focusPath?: string | undefined;
   readonly focusOcc?: number | undefined;
   readonly pathScope?: string;
@@ -122,6 +123,9 @@ export function usePreviewRuntime(
     frame?.postMessage({ type: 'avb:request-render' }, '*');
     link.notify();
   }, [link]);
+  // A flag, not the object: the object is new every render, and re-tracking
+  // makes the frame report rects, which renders again.
+  const annotating = props.feedback !== undefined;
   const sendTrack = useCallback((): void => {
     link.post({
       type: 'avb:track',
@@ -129,8 +133,9 @@ export function usePreviewRuntime(
       scope: props.pathScope ?? '',
       focus: props.focusPath ?? '',
       focusOcc: props.focusOcc ?? 0,
+      annotate: annotating,
     });
-  }, [link, props.focusOcc, props.focusPath, props.pathScope, trackPaths]);
+  }, [annotating, link, props.focusOcc, props.focusPath, props.pathScope, trackPaths]);
   useFrameRegistration(props, url, registerFrame, sendTrack);
   useSelectionScroll(props, iframeRef, refs);
   useResetOnReload(props, url, refs, setters);
@@ -317,17 +322,17 @@ function applyMessage(
       setModifiers({ shiftKey: message.shiftKey, altKey: message.altKey });
       break;
     case 'hover-node':
-      // A picture, not a selection: only the rendering has to be the latest.
-      if (judgeEventToken(message.token, refs.render.current).tag === 'current') {
-        setters.setCanvasHover(message.path);
-        setters.setHoverOcc(message.occurrence);
-      } else {
-        setters.setCanvasHover(undefined);
-      }
+      applyHover(message, refs, setters);
       break;
     case 'context-node':
       applyContextMenu(message, refs, setters, frame);
       break;
+    case 'annotate-node':
+      // A note's trail is read from the files: the rendering has to be them.
+      gateEvent(message.token, refs, { kind: 'open' }, () =>
+        refs.props.current.feedback?.onAnnotate(message),
+      );
+      break;
     case 'click-node':
       gateEvent(
         message.token,
@@ -360,6 +365,20 @@ function applyMessage(
   }
 }
 
+// A picture, not a selection: only the rendering has to be the latest.
+function applyHover(
+  message: Extract<PreviewMessage, { readonly kind: 'hover-node' }>,
+  refs: RuntimeRefs,
+  setters: RuntimeSetters,
+): void {
+  if (judgeEventToken(message.token, refs.render.current).tag === 'current') {
+    setters.setCanvasHover(message.path);
+    setters.setHoverOcc(message.occurrence);
+  } else {
+    setters.setCanvasHover(undefined);
+  }
+}
+
 function applyContextMenu(
   message: Extract<PreviewMessage, { readonly kind: 'context-node' }>,
   refs: RuntimeRefs,
@@ -541,7 +560,10 @@ function useTrackPaths(
   props: PreviewRuntimeProps,
   [hoverPath, selectedBoxPath, hoverBoxPath]: readonly (string | undefined)[],
 ): readonly string[] {
-  const pinPaths = props.pins?.map((pin) => pin.path).join('\n') ?? '';
+  const { feedback } = props;
+  const pinPaths = [...(feedback?.pins ?? []), ...(feedback?.composer ? [feedback.composer] : [])]
+    .map((pin) => pin.path)
+    .join('\n');
   const { focusPath, selPath: selectionPath } = props;
   return useMemo(
     () =>
diff --git a/test/electron/handlers/feedbackHandlers.test.ts b/test/electron/handlers/feedbackHandlers.test.ts
index 13bff149..6d4dc974 100644
--- a/test/electron/handlers/feedbackHandlers.test.ts
+++ b/test/electron/handlers/feedbackHandlers.test.ts
@@ -1,8 +1,10 @@
 // Goal: the Feedback file round-trips through the real main handlers, each
-// item carrying a trail resolved from disk, and a malformed file is refused.
+// item carrying a trail resolved from disk; the project's agent instructions
+// name the file once; and a malformed file is refused.
 // Methodology: register main in a windowless VM over a temporary project, write
 // two items (one on a live node, one on a dead key) through the document actor,
-// read them back, then corrupt the file and check the read throws.
+// read them back, check CLAUDE.md, then corrupt the file and check the read throws.
+// A second project keeps an AGENTS.md that CLAUDE.md imports: only AGENTS.md changes.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import * as fs from 'node:fs';
@@ -44,8 +46,36 @@ test('feedback writes resolve trails, create .stacki/, and read back', async (co
   );
   assert.deepEqual(trails, [['src/pages/index.astro:1-3'], ['src/pages/index.astro']]);
 
+  // An agent started in the project finds the file: CLAUDE.md names it, once.
+  const claude = fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf8');
+  assert.match(claude, /^## Stacki feedback\n/);
+  assert.match(claude, /`\.stacki\/feedback\.json`/);
+  await harness.invoke('feedback:write', { projectPath: root, items });
+  assert.equal(fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf8'), claude, 'written once');
+
   fs.writeFileSync(file, '{"version":2,"items":[]}');
   await assert.rejects(harness.invoke('feedback:read', { projectPath: root }), /version 1/);
   fs.rmSync(file);
   assert.deepEqual(await harness.invoke('feedback:read', { projectPath: root }), { items: [] });
 });
+
+test('a kept AGENTS.md gets the note, not the CLAUDE.md importing it', async (context) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'stacki-feedback-agents-'));
+  fs.mkdirSync(path.join(root, 'src/pages'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'user'));
+  fs.writeFileSync(path.join(root, 'package.json'), '{"dependencies":{"astro":"*"}}');
+  fs.writeFileSync(path.join(root, 'AGENTS.md'), '# Rules');
+  fs.writeFileSync(path.join(root, 'CLAUDE.md'), '@AGENTS.md\n');
+  const harness = mainHarness(path.join(root, 'user'));
+  context.after(() => {
+    harness.dispose();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+  await harness.invoke('project:scan', root);
+  await harness.invoke('feedback:write', { projectPath: root, items: [] });
+  assert.match(
+    fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'),
+    /^# Rules\n\n## Stacki feedback/,
+  );
+  assert.equal(fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf8'), '@AGENTS.md\n');
+});
diff --git a/test/helpers/sources.js b/test/helpers/sources.js
index d631836c..310566ae 100644
--- a/test/helpers/sources.js
+++ b/test/helpers/sources.js
@@ -57,6 +57,7 @@ const PANEL_SOURCES = Object.freeze([
   'src/features/content/ContentFields.tsx',
   'src/features/content/ContentView.tsx',
   'src/features/preview/DevOffline.tsx',
+  'src/features/feedback/FeedbackPanel.tsx',
   'src/features/git/GitChip.tsx',
   'src/features/git/GitChipView.tsx',
   'src/features/history/HistoryPanel.tsx',
diff --git a/test/renderer/app/lazyPanels.test.js b/test/renderer/app/lazyPanels.test.js
index 222d5fae..9fa102d7 100644
--- a/test/renderer/app/lazyPanels.test.js
+++ b/test/renderer/app/lazyPanels.test.js
@@ -52,6 +52,7 @@ const LAZY_PANELS = [
   'ContentView',
   'VariablesPanel',
   'VariablesView',
+  'FeedbackPanel',
   'CodePanel',
 ];
 const LAZY_IMPORT = /lazyPanel\(\(\) => import\('([^']+)'\)\)/g;
@@ -99,6 +100,7 @@ test('all optional editors load without hiding the app or replacing its preview'
     await checkCMS(context);
     await checkCodePanel(context);
     await checkCodeWindow(context);
+    await checkFeedback(context);
     assert.equal(gates.requested.size, LAZY_PANELS.length, 'Every lazy editor was exercised');
   } finally {
     await act(() => root.unmount());
@@ -123,6 +125,12 @@ async function checkVariables(context) {
   assert.equal(__lazyPanels.VariablesView.selected.file, 'src/styles/tokens.css');
 }
 
+async function checkFeedback(context) {
+  await context.act(() => railButton(8).click());
+  assertPending(context, 'FeedbackPanel');
+  await releasePanel(context, 'FeedbackPanel');
+}
+
 async function checkCodePanel(context) {
   await context.act(() => railButton(6).click());
   assertPending(context, 'CodePanel');
@@ -395,6 +403,7 @@ function createBridge() {
     },
     gitInfo: async () => ({ isRepo: false }),
     onCssChanged: () => () => {},
+    readFeedback: async () => ({ items: [] }),
   };
   return new Proxy(bridge, {
     get(target, name) {
diff --git a/test/renderer/app/viteModules.test.ts b/test/renderer/app/viteModules.test.ts
index 13db14df..7d53f0be 100644
--- a/test/renderer/app/viteModules.test.ts
+++ b/test/renderer/app/viteModules.test.ts
@@ -11,9 +11,9 @@ import { test } from 'node:test';
 import { SourceTextModule } from 'node:vm';
 import { createServer, type ViteDevServer } from 'vite';
 
-// Includes publishing, project metadata, defaults-canvas, and history payload parsers.
-// The complete current renderer contract graph contains 43 modules.
-const MODULES_MAX = 43;
+// Includes publishing, project metadata, defaults-canvas, history and Feedback payload
+// parsers. The complete current renderer contract graph contains 44 modules.
+const MODULES_MAX = 44;
 // Repository paths; the dev server serves each at `/<path>`.
 const ENTRY_MODULES: ReadonlyArray<{ readonly file: string; readonly exportName: string }> = [
   { file: 'src/lib/cleanError.ts', exportName: 'cleanError' },
diff --git a/test/renderer/feedback/feedback.test.js b/test/renderer/feedback/feedback.test.js
index 15914df1..1e1fe277 100644
--- a/test/renderer/feedback/feedback.test.js
+++ b/test/renderer/feedback/feedback.test.js
@@ -1,8 +1,9 @@
 // Goal: the Feedback panel trusts only parsed replies, hands the agent the open
-// items in order, and pins a note only where its node is on the canvas.
-// Methodology: parse a good reply and one missing `done`; render the handoff
-// for a mix of open and done items; then run the pin rule against the three
-// cases that decide it (same page, drilled into a component, another page).
+// items in order under the file's absolute path, and pins a note only on the
+// page it was left on. Methodology: parse a good reply and one missing `done`;
+// render the handoff for a mix of open and done items; then run the pin rule
+// over notes on this page (inside a component too), another page, an agent's
+// own note without a canvas place, and a done one.
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const loadRenderer = require('../../helpers/rendererModule');
@@ -10,32 +11,41 @@ const loadRenderer = require('../../helpers/rendererModule');
 const bridge = loadRenderer('src/features/feedback/feedbackBridge.ts');
 const { feedbackPins } = loadRenderer('src/features/feedback/feedbackState.ts');
 
-const item = (id, keys, trail, done = false) => ({
+const item = (id, keys, trail, extra = {}) => ({
   id,
   keys,
   label: 'h1',
   note: `Note ${id}`,
-  done,
+  done: false,
   trail,
+  ...extra,
 });
 
 test('replies parse completely or not at all', () => {
-  const good = item('a', ['src/pages/index.astro#0'], ['src/pages/index.astro:1-3']);
+  const good = item('a', ['src/pages/index.astro#0'], ['src/pages/index.astro:1-3'], {
+    marker: { path: '0', occurrence: 0 },
+  });
   assert.deepEqual(bridge.parseFeedbackReply({ items: [good] }), [good]);
   const { done: _done, ...missingDone } = good;
   assert.throws(() => bridge.parseFeedbackReply({ items: [missingDone] }), /Expected boolean/);
   assert.throws(() => bridge.parseFeedbackReply({ items: [{ ...good, trail: [1] }] }), /string/);
+  const badMarker = { ...good, marker: { path: '0', occurrence: -1 } };
+  assert.throws(() => bridge.parseFeedbackReply({ items: [badMarker] }), /nonnegative/);
 });
 
-test('the handoff numbers open items only and joins a trail with ›', () => {
-  const text = bridge.renderHandoff([
-    item('a', [], ['src/pages/index.astro:12-18']),
-    item('b', [], ['src/pages/index.astro:30'], true),
-    item('c', [], ['src/pages/index.astro:31-33', 'src/components/Hero.astro:9-14']),
-    item('d', [], []),
-  ]);
+test('the handoff names the file absolutely and numbers open items only', () => {
+  const text = bridge.renderHandoff(
+    [
+      item('a', [], ['src/pages/index.astro:12-18']),
+      item('b', [], ['src/pages/index.astro:30'], { done: true }),
+      item('c', [], ['src/pages/index.astro:31-33', 'src/components/Hero.astro:9-14']),
+      item('d', [], []),
+    ],
+    '/sites/my-site',
+  );
   const lines = text.split('\n');
-  assert.match(lines[0], /^Address the open items in \.stacki\/feedback\.json \(3 open\)\./);
+  assert.match(lines[0], /^Address the open items in \/sites\/my-site\/\.stacki\/feedback\.json/);
+  assert.match(lines[0], /\(3 open\)\. Trails are relative to \/sites\/my-site\./);
   assert.deepEqual(lines.slice(2), [
     '1. src/pages/index.astro:12-18 (h1): Note a',
     '2. src/pages/index.astro:31-33 › src/components/Hero.astro:9-14 (h1): Note c',
@@ -43,25 +53,21 @@ test('the handoff numbers open items only and joins a trail with ›', () => {
   ]);
 });
 
-test('a note pins only at its own level of the editing stack', () => {
+test('a note pins on the page it was left on, at its copy of the element', () => {
   const page = 'src/pages/index.astro';
-  const host = `${page}#0.4`;
+  const hero = 'src/components/Hero.astro';
   const items = [
-    item('onPage', [`${page}#0.2.1`], []),
-    item('inHero', [host, 'src/components/Hero.astro#1.0'], []),
-    item('otherPage', ['src/pages/about.astro#0'], []),
-    item('pageNote', [`${page}#`], []),
-    item('done', [`${page}#0`], [], true),
+    item('onPage', [`${page}#0.2.1`], [], { marker: { path: '0.2.1', occurrence: 0 } }),
+    item('inHero', [`${page}#0.4`, `${hero}#1.0`], [], {
+      marker: { path: `${hero}|1.0`, occurrence: 2 },
+    }),
+    item('otherPage', ['src/pages/about.astro#0'], [], { marker: { path: '0', occurrence: 0 } }),
+    item('agent', [], []),
+    item('done', [`${page}#0`], [], { done: true, marker: { path: '0', occurrence: 0 } }),
   ];
-  assert.deepEqual(feedbackPins(items, { selectionKeys: [`${page}#0`], editedRel: undefined }), [
-    { id: 'onPage', path: '0.2.1', index: 1, note: 'Note onPage' },
-  ]);
-  const drilled = {
-    selectionKeys: [host, 'src/components/Hero.astro#'],
-    editedRel: 'src/components/Hero.astro',
-  };
-  assert.deepEqual(feedbackPins(items, drilled), [
-    { id: 'inHero', path: 'src/components/Hero.astro|1.0', index: 2, note: 'Note inHero' },
+  assert.deepEqual(feedbackPins(items, page), [
+    { id: 'onPage', path: '0.2.1', occurrence: 0, index: 1, note: 'Note onPage' },
+    { id: 'inHero', path: `${hero}|1.0`, occurrence: 2, index: 2, note: 'Note inHero' },
   ]);
-  assert.deepEqual(feedbackPins(items, { selectionKeys: [], editedRel: undefined }), []);
+  assert.deepEqual(feedbackPins(items, 'src/pages/blog.astro'), []);
 });
diff --git a/test/renderer/preview/outlines.test.js b/test/renderer/preview/outlines.test.js
index 8046532a..ad6b312f 100644
--- a/test/renderer/preview/outlines.test.js
+++ b/test/renderer/preview/outlines.test.js
@@ -581,6 +581,38 @@ const stacked = (layers, opacity = 0.14) => 1 - (1 - opacity) ** layers;
     );
   }
 
+  // --- annotating (the Feedback tab) -------------------------------------------
+  // A click reaches inside a component without drilling in, and reports the
+  // files it renders through, outermost first: the page's instance of the card,
+  // then the card's own text. The second card is the second copy of that text.
+  {
+    const track = new window.MessageEvent('message', {
+      data: { type: 'avb:track', paths: [], scope: '', annotate: true },
+    });
+    Object.defineProperty(track, 'source', { value: window.parent });
+    window.dispatchEvent(track);
+    const element = document.querySelector('[data-box="card-two-text"]');
+    sent.length = 0;
+    element.dispatchEvent(new window.MouseEvent('click', { bubbles: true, cancelable: true }));
+    const annotation = sent.find((message) => message.type === 'avb:annotate-node');
+    check(
+      'an annotating click names the element inside the component',
+      annotation?.path === 'src/components/Card.astro|0.0.0.1' && annotation?.occurrence === 1,
+      JSON.stringify(annotation),
+    );
+    check(
+      'with the page instance first, then the component',
+      JSON.stringify(annotation?.chain) ===
+        JSON.stringify([
+          { file: '', path: '0.6.1' },
+          { file: 'src/components/Card.astro', path: '0.0.0.1' },
+        ]),
+      JSON.stringify(annotation?.chain),
+    );
+    check('and selects nothing', !sent.some((message) => message.type === 'avb:click-node'));
+    check('labelled by its tag', annotation?.label === 'span', JSON.stringify(annotation));
+  }
+
   if (failures.length) {
     console.error(`\noutlines: ${failures.length} failed, ${checked - failures.length} passed\n`);
     console.error(failures.join('\n') + '\n');
diff --git a/test/renderer/preview/pinOverlays.test.js b/test/renderer/preview/pinOverlays.test.js
index cb361bf0..26634114 100644
--- a/test/renderer/preview/pinOverlays.test.js
+++ b/test/renderer/preview/pinOverlays.test.js
@@ -1,7 +1,8 @@
-// Goal: a Feedback pin draws at its node's first box, scaled like the outlines,
-// and draws nothing when the frame reported no box for it.
-// Methodology: render the overlay layer to static markup with one measured pin
-// and one unmeasured pin, then read the pins back out of the markup.
+// Goal: a Feedback pin draws on its own copy of its element, scaled like the
+// outlines, and draws nothing when the frame reported no box for it; an open
+// pin shows its note, and the note box sits under the element just clicked.
+// Methodology: render the overlay layer to static markup with a measured pin
+// on the second copy, an unmeasured pin, and a composer, then read them back.
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
@@ -27,7 +28,12 @@ test('pins draw where their node has a box', () => {
   const { PreviewOverlays } = require(output);
   const markup = renderToStaticMarkup(
     React.createElement(PreviewOverlays, {
-      rects: { 0.2: [{ x: 10, y: 20, w: 100, h: 40 }] },
+      rects: {
+        0.2: [
+          { x: 0, y: 0, w: 10, h: 10 },
+          { x: 10, y: 20, w: 100, h: 40 },
+        ],
+      },
       spacing: {},
       scale: 0.5,
       selPath: undefined,
@@ -36,15 +42,29 @@ test('pins draw where their node has a box', () => {
       hoverOcc: undefined,
       focusPath: undefined,
       focusWhole: false,
-      pins: [
-        { id: 'a', path: '0.2', index: 1, note: 'Measured' },
-        { id: 'b', path: '0.9', index: 2, note: 'Not rendered' },
-      ],
+      feedback: {
+        pins: [
+          { id: 'a', path: '0.2', occurrence: 1, index: 1, note: 'Measured' },
+          { id: 'b', path: '0.9', occurrence: 0, index: 2, note: 'Not rendered' },
+        ],
+        openPinId: 'a',
+        composer: { path: '0.2', occurrence: 1, target: 'div.hero' },
+        onAnnotate: () => {},
+        onAdd: () => {},
+        onCancel: () => {},
+        onOpenPin: () => {},
+        onDone: () => {},
+        onRemove: () => {},
+      },
     }),
   );
-  const pins = [...markup.matchAll(/<button class="feedback-pin"[^>]*>(\d+)<\/button>/g)];
+  const pins = [
+    ...markup.matchAll(/<div style="([^"]*)"><button class="feedback-pin[^"]*"[^>]*>(\d+)/g),
+  ];
   assert.equal(pins.length, 1, markup);
-  assert.equal(pins[0][1], '1');
-  assert.match(pins[0][0], /title="Measured"/);
-  assert.match(pins[0][0], /left:5px;top:10px/);
+  assert.equal(pins[0][2], '1');
+  assert.match(pins[0][1], /left:5px;top:10px/);
+  assert.match(markup, /<p class="feedback-card-note">Measured<\/p>/);
+  assert.match(markup, /class="feedback-card feedback-composer" style="left:5px;top:36px"/);
+  assert.match(markup, /placeholder="Note on div.hero"/);
 });

From 06b8379c40ab7c8ec67a717417eaf6191ac4b961 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 11:47:03 +0000
Subject: [PATCH 3/8] fix: style the Feedback note box and pin cards

They had no CSS, so the note box rendered unpositioned at the top of the
canvas, inside an overlay layer that ignores the pointer (and children
inherit that), so it could not be clicked or typed into. Position both
absolutely, give them a surface, and take pointer events back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 src/app/shell/AppPanes.tsx               |  29 +++++-
 src/features/preview/previewViewport.css | 119 +++++++++++++++++++++++
 2 files changed, 147 insertions(+), 1 deletion(-)

diff --git a/src/app/shell/AppPanes.tsx b/src/app/shell/AppPanes.tsx
index 55c76561..003a1c36 100644
--- a/src/app/shell/AppPanes.tsx
+++ b/src/app/shell/AppPanes.tsx
@@ -71,7 +71,7 @@ export function CanvasPane({ app }: { readonly app: ShellView }) {
         onStaleEvent={app.onStaleEvent}
         onPreviewReload={app.onPreviewReload}
         onContextPath={context.open}
-        onSelectPath={(path, info) => selectCanvasPath(app, path ?? undefined, info)}
+        onSelectPath={(path, info) => onCanvasClick(app, path ?? undefined, info)}
         onSelectedClasses={app.receiveClasses}
         onRenderedPaths={app.setRenderedPaths}
         onNodeStates={app.setNodeStates}
@@ -146,6 +146,33 @@ function canvasContextPosition(
   return { ...point, nodeId: node.id };
 }
 
+// While annotating, the frame reports clicks as annotations. A click arrives
+// here only from a frame whose script predates annotating (the dev build
+// rebuilds it only on a restart): annotate the open file's node it names,
+// without reaching inside components, rather than select it.
+function onCanvasClick(
+  app: ShellView,
+  path: string | undefined,
+  info: { readonly outside: boolean },
+): void {
+  if (app.leftTab !== 'feedback') {
+    selectCanvasPath(app, path, info);
+    return;
+  }
+  if (path === undefined) {
+    return;
+  }
+  const bar = path.indexOf('|');
+  app.feedback.compose({
+    path,
+    occurrence: 0,
+    chain: [
+      bar === -1 ? { file: '', path } : { file: path.slice(0, bar), path: path.slice(bar + 1) },
+    ],
+    label: app.overlayInfo(path)?.label ?? 'element',
+  });
+}
+
 // The Feedback tab's hold on the canvas: clicks annotate, pins open notes.
 function canvasFeedback(app: ShellView): CanvasFeedback {
   const { feedback } = app;
diff --git a/src/features/preview/previewViewport.css b/src/features/preview/previewViewport.css
index 750ba11b..3cdd5a25 100644
--- a/src/features/preview/previewViewport.css
+++ b/src/features/preview/previewViewport.css
@@ -84,3 +84,122 @@
   pointer-events: auto;
   cursor: pointer;
 }
+
+/* A Feedback note's card, under its pin, and the box that takes a new note
+   under the element just clicked. The layer ignores the pointer; these take it. */
+.feedback-card {
+  position: absolute;
+  z-index: 2;
+  width: 240px;
+  padding: 8px;
+  color: var(--text);
+  font-size: 11.5px;
+  line-height: 1.4;
+  background: var(--bg-panel-2);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+  pointer-events: auto;
+}
+.feedback-pin + .feedback-card {
+  top: 14px;
+  left: 0;
+}
+.feedback-pin.is-open {
+  outline: 2px solid var(--text);
+}
+.feedback-card-note {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.feedback-composer textarea {
+  display: block;
+  width: 100%;
+  min-height: 56px;
+  resize: vertical;
+  padding: 6px 8px;
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+.feedback-card-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-top: 6px;
+}
+.feedback-card-actions button {
+  padding: 3px 8px;
+  color: var(--text);
+  background: var(--bg-active);
+  border-radius: 5px;
+}
+.feedback-card-actions button.is-primary {
+  color: white;
+  background: var(--accent);
+}
+.feedback-card-actions button:disabled {
+  opacity: 0.5;
+}
+
+/* A Feedback note's card under its pin, and the box that takes a new note
+   under the element just clicked. The layer ignores the pointer; these take it. */
+.feedback-card {
+  position: absolute;
+  z-index: 2;
+  width: 240px;
+  padding: 8px;
+  color: var(--text);
+  font-size: 11.5px;
+  line-height: 1.4;
+  background: var(--bg-panel-2);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+  pointer-events: auto;
+}
+.feedback-pin + .feedback-card {
+  top: 14px;
+  left: 0;
+}
+.feedback-pin.is-open {
+  outline: 2px solid var(--text);
+}
+.feedback-card-note {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.feedback-composer textarea {
+  display: block;
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 56px;
+  resize: vertical;
+  padding: 6px 8px;
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+.feedback-card-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-top: 6px;
+}
+.feedback-card-actions button {
+  padding: 3px 8px;
+  color: var(--text);
+  background: var(--bg-active);
+  border-radius: 5px;
+}
+.feedback-card-actions button.is-primary {
+  color: white;
+  background: var(--accent);
+}
+.feedback-card-actions button:disabled {
+  opacity: 0.5;
+}

From 2477da5b0871043a278653631ed9d1c20379419f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 12:00:23 +0000
Subject: [PATCH 4/8] fix: keep Feedback rows inside the panel

The trail's file:line sat beside the label as one unbreakable monospace
run, so it ran under the done and remove buttons. Give it its own line,
cut with an ellipsis, with the whole trail in its title; let long labels
wrap, and keep the buttons from shrinking.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 src/features/feedback/FeedbackPanel.tsx | 6 +++---
 src/features/feedback/feedback.css      | 7 ++++++-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/features/feedback/FeedbackPanel.tsx b/src/features/feedback/FeedbackPanel.tsx
index ade4d4bb..874a3bc1 100644
--- a/src/features/feedback/FeedbackPanel.tsx
+++ b/src/features/feedback/FeedbackPanel.tsx
@@ -70,9 +70,9 @@ function FeedbackRow(
     >
       <span className="feedback-number">{props.number ?? ''}</span>
       <div className="feedback-main">
-        <div className="feedback-label">
-          {item.label}
-          <span className="feedback-where">{item.trail.at(-1) ?? ''}</span>
+        <div className="feedback-label">{item.label}</div>
+        <div className="feedback-where" title={item.trail.join(' › ')}>
+          {item.trail.at(-1) ?? ''}
         </div>
         <div className="feedback-note">{item.note}</div>
       </div>
diff --git a/src/features/feedback/feedback.css b/src/features/feedback/feedback.css
index 5bcd20e0..04ac2a2b 100644
--- a/src/features/feedback/feedback.css
+++ b/src/features/feedback/feedback.css
@@ -40,12 +40,16 @@
 }
 .feedback-label {
   color: var(--text-dim);
+  overflow-wrap: anywhere;
 }
+/* A file:line on its own line, cut with an ellipsis; the row's title has it whole. */
 .feedback-where {
-  margin-left: 6px;
+  overflow: hidden;
   font-family: var(--mono);
   font-size: 10px;
   color: var(--text-faint);
+  white-space: nowrap;
+  text-overflow: ellipsis;
 }
 .feedback-note {
   color: var(--text);
@@ -53,6 +57,7 @@
   overflow-wrap: anywhere;
 }
 .feedback-row button {
+  flex-shrink: 0;
   padding: 2px;
   color: var(--text-faint);
 }

From 46d1c713835549985bfa7a92045d77cc78797167 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 12:02:43 +0000
Subject: [PATCH 5/8] fix: keep Feedback pins amber on hover

The app's button:hover background replaced the pin's amber, so a hovered
pin all but disappeared. A more specific hover keeps it: a lighter amber,
a slight grow and a shadow, eased over 120ms. The note box's primary
button keeps its blue the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 src/features/preview/previewViewport.css | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/features/preview/previewViewport.css b/src/features/preview/previewViewport.css
index 3cdd5a25..25e2325c 100644
--- a/src/features/preview/previewViewport.css
+++ b/src/features/preview/previewViewport.css
@@ -83,6 +83,16 @@
   text-align: center;
   pointer-events: auto;
   cursor: pointer;
+  transition:
+    transform 120ms ease-out,
+    background-color 120ms ease-out,
+    box-shadow 120ms ease-out;
+}
+/* Beats the app's button:hover background, which would hide the amber. */
+.preview-overlay-layer .feedback-pin:hover {
+  transform: translate(-50%, -50%) scale(1.2);
+  background: #ffe55c;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35);
 }
 
 /* A Feedback note's card, under its pin, and the box that takes a new note
@@ -136,7 +146,8 @@
   background: var(--bg-active);
   border-radius: 5px;
 }
-.feedback-card-actions button.is-primary {
+.feedback-card-actions button.is-primary,
+.preview-overlay-layer .feedback-card-actions button.is-primary:hover:not(:disabled) {
   color: white;
   background: var(--accent);
 }

From 040b67ad2720058cbe61f45f65337f2eaf2f07da Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 20 Oct 2026 12:05:41 +0000
Subject: [PATCH 6/8] fix: say any local agent, not Claude Code, in the copy
 toast

Copy for agent works with whatever agent runs in the project folder, so
the toast no longer names one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DAFvSVVtdvBZHDz2thvb12
---
 src/features/feedback/FeedbackPanel.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/features/feedback/FeedbackPanel.tsx b/src/features/feedback/FeedbackPanel.tsx
index 874a3bc1..bd65cbfe 100644
--- a/src/features/feedback/FeedbackPanel.tsx
+++ b/src/features/feedback/FeedbackPanel.tsx
@@ -20,7 +20,10 @@ export default function FeedbackPanel(props: FeedbackPanelProps) {
   const copy = async (): Promise<void> => {
     try {
       await navigator.clipboard.writeText(renderHandoff(feedback.items, props.projectPath));
-      props.showToast('Copied. Paste it into Claude Code in the project.', 'success');
+      props.showToast(
+        'Copied. Paste into any agent running locally in your project folder.',
+        'success',
+      );
     } catch {
       props.showToast('Could not copy the feedback.', 'error');
     }

From 47fc612870ea186ed0fdd2cc65c3ce6923f5e901 Mon Sep 17 00:00:00 2001
From: patmw <pmassowalsh@gmail.com>
Date: Tue, 20 Oct 2026 20:10:18 +0100
Subject: [PATCH 7/8] fix: keep .stacki/feedback.json out of project commits

The project's .stacki/ folder is now tracked so shared settings reach Git
and Studio; only generated folders stay in the local exclude. Feedback
notes are the editor's working state, not site source, so the file joins
.stacki/preview/ and .stacki/canvas/ in .git/info/exclude. The handler
test asks Git directly whether it ignores the file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 electron/lib/projectExclusions.ts               |  7 ++++---
 test/electron/handlers/feedbackHandlers.test.ts | 17 ++++++++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/electron/lib/projectExclusions.ts b/electron/lib/projectExclusions.ts
index b4ef5d95..d44a9e59 100644
--- a/electron/lib/projectExclusions.ts
+++ b/electron/lib/projectExclusions.ts
@@ -1,10 +1,11 @@
 // Git's local exclude is repository bookkeeping, never website source.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-const EXCLUDE_LINES = ['.stacki/preview/', '.stacki/canvas/'];
+const EXCLUDE_LINES = ['.stacki/preview/', '.stacki/canvas/', '.stacki/feedback.json'];
 
 /**
- * Keep generated preview checkouts and defaults canvases out of project commits.
+ * Keep generated preview checkouts, defaults canvases and the editor's
+ * feedback notes out of project commits.
  *
  * Without this the preview checkout shows up as an untracked folder in the
  * user's own project — in the file picker, in the commit box, in every status
@@ -54,7 +55,7 @@ export function ensureExcluded(projectPath: string): boolean {
     const next =
       missing.length === 0
         ? current
-        : current + sep + '# Stacki previews (generated).\n' + missing.join('\n') + '\n';
+        : current + sep + '# Stacki local files (generated).\n' + missing.join('\n') + '\n';
     fs.writeFileSync(file, next);
     return true;
   } catch {
diff --git a/test/electron/handlers/feedbackHandlers.test.ts b/test/electron/handlers/feedbackHandlers.test.ts
index 6d4dc974..2b1cf9cc 100644
--- a/test/electron/handlers/feedbackHandlers.test.ts
+++ b/test/electron/handlers/feedbackHandlers.test.ts
@@ -1,12 +1,14 @@
 // Goal: the Feedback file round-trips through the real main handlers, each
-// item carrying a trail resolved from disk; the project's agent instructions
-// name the file once; and a malformed file is refused.
+// item carrying a trail resolved from disk; Git never sees the file; the
+// project's agent instructions name the file once; and a malformed file is refused.
 // Methodology: register main in a windowless VM over a temporary project, write
 // two items (one on a live node, one on a dead key) through the document actor,
-// read them back, check CLAUDE.md, then corrupt the file and check the read throws.
+// read them back, ask Git whether it ignores the file, check CLAUDE.md, then
+// corrupt the file and check the read throws.
 // A second project keeps an AGENTS.md that CLAUDE.md imports: only AGENTS.md changes.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -28,6 +30,7 @@ test('feedback writes resolve trails, create .stacki/, and read back', async (co
   fs.mkdirSync(path.join(root, 'user'));
   fs.writeFileSync(path.join(root, 'package.json'), '{"dependencies":{"astro":"*"}}');
   fs.writeFileSync(path.join(root, 'src/pages/index.astro'), '<main>\n  <h1>Hi</h1>\n</main>\n');
+  execFileSync('git', ['init', '--quiet'], { cwd: root });
   const harness = mainHarness(path.join(root, 'user'));
   context.after(() => {
     harness.dispose();
@@ -46,6 +49,14 @@ test('feedback writes resolve trails, create .stacki/, and read back', async (co
   );
   assert.deepEqual(trails, [['src/pages/index.astro:1-3'], ['src/pages/index.astro']]);
 
+  // The notes are the editor's, not the site's: Git ignores them, so they never
+  // reach a commit, while the rest of `.stacki/` stays the project's to track.
+  const ignored = execFileSync('git', ['check-ignore', '.stacki/feedback.json'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  assert.equal(ignored.trim(), '.stacki/feedback.json');
+
   // An agent started in the project finds the file: CLAUDE.md names it, once.
   const claude = fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf8');
   assert.match(claude, /^## Stacki feedback\n/);

From 153c838e69bbd63f1728a8269dc3686287daba51 Mon Sep 17 00:00:00 2001
From: patmw <pmassowalsh@gmail.com>
Date: Wed, 21 Oct 2026 00:13:47 +0100
Subject: [PATCH 8/8] feat: reveal a Feedback note from the list, on any page

A click on a row now always brings its note on screen. A note on another
page opens that page first; a note out of view scrolls the canvas to it.
Before, a row did anything only when its pin was already drawn on the
open page.

The row asks useFeedback to reveal the item. feedbackRevealPlan finds the
note's page among its selection keys: they are not in page-first order
(content a page slots into its layout lists the layout first), so the
open page is matched by the same any-key rule its pins use, and otherwise
the first key naming one of the project's pages is opened through the
page switcher's own selectPage. A note whose page is gone says so.

The canvas half waits in useFeedbackReveal: once the pin exists and the
frame showing its page has measured it, it posts the same avb:scroll-to
the navigator uses, once. Rects held when the frame changed pages are
refused, because index paths repeat across pages and a match among the
previous page's would scroll to the wrong element.

Done notes and an agent's notes without a canvas place have no pin, so
their rows still only show the note in the list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/app/shell/AppPanes.tsx               |  2 +
 src/app/state/appComposers.ts            | 14 ++++-
 src/features/feedback/FeedbackPanel.tsx  | 16 ++++--
 src/features/feedback/feedbackState.ts   | 72 +++++++++++++++++++++++-
 src/features/preview/PreviewOverlays.tsx |  3 +
 src/features/preview/feedbackReveal.ts   | 64 +++++++++++++++++++++
 src/features/preview/previewRuntime.ts   |  2 +
 test/renderer/feedback/feedback.test.js  | 72 +++++++++++++++++++++++-
 8 files changed, 234 insertions(+), 11 deletions(-)
 create mode 100644 src/features/preview/feedbackReveal.ts

diff --git a/src/app/shell/AppPanes.tsx b/src/app/shell/AppPanes.tsx
index 003a1c36..04ef8193 100644
--- a/src/app/shell/AppPanes.tsx
+++ b/src/app/shell/AppPanes.tsx
@@ -184,6 +184,8 @@ function canvasFeedback(app: ShellView): CanvasFeedback {
     onAdd: (note) => void feedback.add(note),
     onCancel: feedback.cancel,
     onOpenPin: feedback.setOpenPinId,
+    revealId: feedback.revealId,
+    onRevealed: feedback.revealed,
     onDone: (id) => void feedback.toggleDone(id),
     onRemove: (id) => void feedback.remove(id),
   };
diff --git a/src/app/state/appComposers.ts b/src/app/state/appComposers.ts
index e6ddf361..8b5b6e08 100644
--- a/src/app/state/appComposers.ts
+++ b/src/app/state/appComposers.ts
@@ -34,6 +34,8 @@ import {
   useOverlayInfo,
 } from './appViewModel';
 import { useFeedback } from '../../features/feedback/feedbackState';
+import { projectRelativePath } from '../../lib/projectPath';
+import { assert } from '../../../shared/core/assert';
 
 // Every piece of the app's state and behaviour, in the order its hooks run.
 export function useAppScope() {
@@ -48,10 +50,20 @@ export function useAppScope() {
   const viewModel = useViewModel(coreState, lifecycle, shortcuts, pageOps);
   // After the view model: it sets the selection keys, whose first names the page.
   const pageKey = coreState.selectionKeysRef.current[0];
+  const projectPath = coreState.project?.path;
+  const relOf = (file: string): string =>
+    projectRelativePath(projectPath ?? '', file, window.avb.platform);
   const feedback = useFeedback({
-    projectPath: coreState.project?.path,
+    projectPath,
     active: coreState.leftTab === 'feedback',
     pageRel: pageKey === undefined ? undefined : pageKey.slice(0, pageKey.indexOf('#')),
+    pageRels: projectPath === undefined ? [] : coreState.scan.pages.map((page) => relOf(page.path)),
+    openPage: (pageRel) => {
+      const page = coreState.scan.pages.find((candidate) => relOf(candidate.path) === pageRel);
+      assert(page !== undefined, 'A note opens only one of the project’s pages');
+      // Opening a page reports its own failures.
+      void navigation.selectPage(page);
+    },
     showToast: lifecycle.showToast,
   });
   return {
diff --git a/src/features/feedback/FeedbackPanel.tsx b/src/features/feedback/FeedbackPanel.tsx
index bd65cbfe..61ebe264 100644
--- a/src/features/feedback/FeedbackPanel.tsx
+++ b/src/features/feedback/FeedbackPanel.tsx
@@ -63,14 +63,18 @@ function FeedbackRow(
   },
 ) {
   const { item, feedback } = props;
-  // A row with a pin on this page opens it, so the note shows where it was left.
-  const pinned = feedback.pins.some((pin) => pin.id === item.id);
   const open = feedback.openPinId === item.id ? ' is-selected' : '';
+  // A row reveals its note where it was left, opening its page and scrolling
+  // the canvas to it; a second click closes the note again.
+  const onClick = (): void => {
+    if (open) {
+      feedback.setOpenPinId(undefined);
+    } else {
+      feedback.reveal(item.id);
+    }
+  };
   return (
-    <div
-      className={`feedback-row${item.done ? ' is-done' : ''}${open}`}
-      onClick={() => pinned && feedback.setOpenPinId(open ? undefined : item.id)}
-    >
+    <div className={`feedback-row${item.done ? ' is-done' : ''}${open}`} onClick={onClick}>
       <span className="feedback-number">{props.number ?? ''}</span>
       <div className="feedback-main">
         <div className="feedback-label">{item.label}</div>
diff --git a/src/features/feedback/feedbackState.ts b/src/features/feedback/feedbackState.ts
index c3e056ee..73c0bed4 100644
--- a/src/features/feedback/feedbackState.ts
+++ b/src/features/feedback/feedbackState.ts
@@ -26,6 +26,13 @@ export interface FeedbackAnnotation {
   readonly label: string;
 }
 
+/** What a click on a row has to do to bring its note on screen. */
+export type FeedbackRevealPlan =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'here' }
+  | { readonly kind: 'open-page'; readonly page: string }
+  | { readonly kind: 'no-page' };
+
 interface Composing {
   readonly keys: readonly string[];
   readonly marker: { readonly path: string; readonly occurrence: number };
@@ -38,6 +45,10 @@ interface FeedbackContext {
   readonly active: boolean;
   /** The open page, project-relative: what a chain's '' file means. */
   readonly pageRel: string | undefined;
+  /** The project's pages, project-relative: which of a note's files is its page. */
+  readonly pageRels: readonly string[];
+  /** Opens one of `pageRels`. */
+  readonly openPage: (pageRel: string) => void;
   readonly showToast: (message: string, kind: 'error') => void;
 }
 
@@ -46,6 +57,8 @@ export function useFeedback(context: FeedbackContext) {
   const { items, reload, change } = useFeedbackFile(context);
   const [composing, setComposing] = useState<Composing | undefined>(undefined);
   const [openPinId, setOpenPinId] = useState<string | undefined>(undefined);
+  // The pin the canvas still has to scroll to: its page may yet be loading.
+  const [revealId, setRevealId] = useState<string | undefined>(undefined);
   const pins = useMemo(
     () => (active && pageRel ? feedbackPins(items, pageRel) : []),
     [active, items, pageRel],
@@ -79,8 +92,28 @@ export function useFeedback(context: FeedbackContext) {
   const composer =
     active && composing ? { ...composing.marker, target: composing.label } : undefined;
   const cancel = (): void => setComposing(undefined);
-  const actions = { reload, compose, add, cancel, toggleDone, remove, clearDone };
-  return { feedback: { items, pins, composer, openPinId, setOpenPinId, ...actions } };
+  // A row brings its note on screen: the page it was left on opens when another
+  // one is showing, and the canvas scrolls to the pin once that page measures it.
+  const reveal = (id: string): void => {
+    const item = items.find((candidate) => candidate.id === id);
+    const plan = feedbackRevealPlan(item, { pageRel, pageRels: context.pageRels });
+    if (plan.kind === 'none') {
+      return;
+    }
+    if (plan.kind === 'no-page') {
+      context.showToast('The page this note was left on is no longer in the project.', 'error');
+      return;
+    }
+    setComposing(undefined);
+    setOpenPinId(id);
+    setRevealId(id);
+    if (plan.kind === 'open-page') {
+      context.openPage(plan.page);
+    }
+  };
+  const revealed = (): void => setRevealId(undefined);
+  const actions = { reload, compose, add, cancel, toggleDone, remove, clearDone, reveal, revealed };
+  return { feedback: { items, pins, composer, openPinId, setOpenPinId, revealId, ...actions } };
 }
 
 // The file's items while the tab is open: read on opening, on window focus, and
@@ -143,6 +176,41 @@ function newItem(composing: Composing, note: string): FeedbackItem {
   };
 }
 
+/**
+ * Where a row's note is: nowhere on the canvas (done, or an agent's own item
+ * without a place), on the open page, on another page that has to open first,
+ * or on a page the project no longer has. A note's keys are not in page-first
+ * order (content a page slots into its layout lists the layout first), so the
+ * page is whichever key names one: the open page by the same rule its pins use,
+ * otherwise the first key naming any of the project's pages.
+ */
+export function feedbackRevealPlan(
+  item: TrailedFeedbackItem | undefined,
+  pages: { readonly pageRel: string | undefined; readonly pageRels: readonly string[] },
+): FeedbackRevealPlan {
+  if (item === undefined) {
+    return { kind: 'none' };
+  }
+  if (item.done) {
+    return { kind: 'none' };
+  }
+  if (item.marker === undefined) {
+    return { kind: 'none' };
+  }
+  const files = item.keys.map((key) => {
+    assert(key.includes('#'), 'A selection key names its file before the #');
+    return key.slice(0, key.indexOf('#'));
+  });
+  assert(files.length === item.keys.length, 'Every key names a file');
+  if (pages.pageRel !== undefined) {
+    if (files.includes(pages.pageRel)) {
+      return { kind: 'here' };
+    }
+  }
+  const page = files.find((file) => pages.pageRels.includes(file));
+  return page === undefined ? { kind: 'no-page' } : { kind: 'open-page', page };
+}
+
 /**
  * The open items that draw on the canvas: those left on the open page that
  * know where they were clicked. Everything else (another page, an agent's own
diff --git a/src/features/preview/PreviewOverlays.tsx b/src/features/preview/PreviewOverlays.tsx
index 5d02426b..ddd2d0a3 100644
--- a/src/features/preview/PreviewOverlays.tsx
+++ b/src/features/preview/PreviewOverlays.tsx
@@ -50,6 +50,9 @@ export interface CanvasFeedback {
   readonly onAdd: (note: string) => void;
   readonly onCancel: () => void;
   readonly onOpenPin: (id: string | undefined) => void;
+  /** A pin the Feedback list asked to bring on screen, until the canvas has. */
+  readonly revealId: string | undefined;
+  readonly onRevealed: () => void;
   readonly onDone: (id: string) => void;
   readonly onRemove: (id: string) => void;
 }
diff --git a/src/features/preview/feedbackReveal.ts b/src/features/preview/feedbackReveal.ts
new file mode 100644
index 00000000..e11166dc
--- /dev/null
+++ b/src/features/preview/feedbackReveal.ts
@@ -0,0 +1,64 @@
+// Bringing a Feedback pin on screen when the Feedback list asks for it. The
+// pin may sit on a page that is still loading, so the request waits until the
+// frame showing that page has measured the pin, then scrolls to it once.
+import { useEffect, useRef } from 'react';
+import { assert } from '../../../shared/core/assert';
+import type { CanvasFeedback, PinOverlay, RectMap } from './PreviewOverlays';
+
+export function useFeedbackReveal(
+  feedback: CanvasFeedback | undefined,
+  rects: RectMap,
+  url: string | undefined,
+  post: (message: unknown) => void,
+): void {
+  // The rects held when the frame last changed pages. They name the previous
+  // page's nodes, and index paths repeat across pages, so a match among them
+  // would scroll to the wrong element; the reload clears them shortly after.
+  const reload = useRef<{ readonly url: string | undefined; readonly stale?: RectMap }>({ url });
+  if (reload.current.url !== url) {
+    reload.current = { url, stale: rects };
+  }
+  const stale = reload.current.stale;
+  const revealId = feedback?.revealId;
+  const pins = feedback?.pins;
+  const onRevealed = feedback?.onRevealed;
+  useEffect(() => {
+    if (revealId === undefined || pins === undefined || onRevealed === undefined) {
+      return;
+    }
+    const pin = revealTarget({ revealId, pins, rects, stale });
+    if (pin !== undefined) {
+      // The frame scrolls only when the element is out of sight.
+      post({ type: 'avb:scroll-to', path: pin.path, occ: pin.occurrence });
+      onRevealed();
+    }
+  }, [onRevealed, pins, post, rects, revealId, stale]);
+}
+
+/**
+ * The pin to scroll to, once it can be: it is on the open page (it has a pin)
+ * and the frame showing that page has measured it. Undefined means wait.
+ */
+export function revealTarget(input: {
+  readonly revealId: string;
+  readonly pins: readonly PinOverlay[];
+  readonly rects: RectMap;
+  readonly stale: RectMap | undefined;
+}): PinOverlay | undefined {
+  const pin = input.pins.find((candidate) => candidate.id === input.revealId);
+  if (pin === undefined) {
+    return undefined; // Its page has not opened yet.
+  }
+  assert(pin.id === input.revealId, 'The pin found is the one asked for');
+  if (input.rects === input.stale) {
+    return undefined; // These rects are the previous page's.
+  }
+  const measured = input.rects[pin.path];
+  if (measured === undefined) {
+    return undefined;
+  }
+  if (measured.length === 0) {
+    return undefined;
+  }
+  return pin;
+}
diff --git a/src/features/preview/previewRuntime.ts b/src/features/preview/previewRuntime.ts
index c5e5e033..cb046c26 100644
--- a/src/features/preview/previewRuntime.ts
+++ b/src/features/preview/previewRuntime.ts
@@ -7,6 +7,7 @@ import type { PreviewMessage, PreviewReloadReason } from './previewMessages';
 import type { GuideMetrics } from './guideModel';
 import { parsePreviewMessage } from './previewMessages';
 import { outlineBoxPath, sameCopy } from './outlineBoxes';
+import { useFeedbackReveal } from './feedbackReveal';
 import { setModifiers } from '../../editor/heldModifiers';
 import { noteCanvasReady, receiveCanvasReply, setCanvasFrame } from '../../editor/canvasQuery';
 import type { Digest } from '../../../shared/core/brand';
@@ -139,6 +140,7 @@ export function usePreviewRuntime(
   useFrameRegistration(props, url, registerFrame, sendTrack);
   useSelectionScroll(props, iframeRef, refs);
   useResetOnReload(props, url, refs, setters);
+  useFeedbackReveal(props.feedback, rects, url, link.post);
   return {
     iframeRef,
     rects,
diff --git a/test/renderer/feedback/feedback.test.js b/test/renderer/feedback/feedback.test.js
index 1e1fe277..2303ddf1 100644
--- a/test/renderer/feedback/feedback.test.js
+++ b/test/renderer/feedback/feedback.test.js
@@ -3,13 +3,17 @@
 // page it was left on. Methodology: parse a good reply and one missing `done`;
 // render the handoff for a mix of open and done items; then run the pin rule
 // over notes on this page (inside a component too), another page, an agent's
-// own note without a canvas place, and a done one.
+// own note without a canvas place, and a done one. Revealing a note from the
+// list is checked in two halves: the plan (stay, open its page, or nothing)
+// over the same kinds of note, and the canvas's wait for the pin to be measured
+// on a fresh page before it scrolls, never on the previous page's rects.
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const loadRenderer = require('../../helpers/rendererModule');
 
 const bridge = loadRenderer('src/features/feedback/feedbackBridge.ts');
-const { feedbackPins } = loadRenderer('src/features/feedback/feedbackState.ts');
+const { feedbackPins, feedbackRevealPlan } = loadRenderer('src/features/feedback/feedbackState.ts');
+const { revealTarget } = loadRenderer('src/features/preview/feedbackReveal.ts');
 
 const item = (id, keys, trail, extra = {}) => ({
   id,
@@ -71,3 +75,67 @@ test('a note pins on the page it was left on, at its copy of the element', () =>
   ]);
   assert.deepEqual(feedbackPins(items, 'src/pages/blog.astro'), []);
 });
+
+test('revealing a note stays on its page or opens it first', () => {
+  // Real key order: content a page slots into its layout lists the layout first,
+  // so the page is found among the keys, never assumed to be the first.
+  const layout = 'src/layouts/BaseLayout.astro#1.1.2.0';
+  const section = 'src/components/wrapper/Section.astro#0.0.0.1.0.0.0';
+  const heading = 'src/components/typography/Heading.astro#0.0.0';
+  const marker = { path: 'src/components/typography/Heading.astro|0.0.0', occurrence: 0 };
+  const onHome = item('home', [layout, section, 'src/pages/index.astro#0.0.0.1', heading], [], {
+    marker,
+  });
+  const onMissing = item('404', [layout, section, 'src/pages/404.astro#0.0.0.0', heading], [], {
+    marker,
+  });
+  const pageRels = ['src/pages/index.astro', 'src/pages/404.astro'];
+  const at = (pageRel) => ({ pageRel, pageRels });
+  assert.deepEqual(feedbackRevealPlan(onHome, at('src/pages/index.astro')), { kind: 'here' });
+  assert.deepEqual(feedbackRevealPlan(onMissing, at('src/pages/index.astro')), {
+    kind: 'open-page',
+    page: 'src/pages/404.astro',
+  });
+  // With no page open yet, a placed note still has its page to open.
+  assert.deepEqual(feedbackRevealPlan(onHome, at(undefined)), {
+    kind: 'open-page',
+    page: 'src/pages/index.astro',
+  });
+  // Its page was deleted: the layout and components are not pages to open.
+  assert.deepEqual(
+    feedbackRevealPlan(onMissing, {
+      pageRel: 'src/pages/index.astro',
+      pageRels: pageRels.slice(0, 1),
+    }),
+    { kind: 'no-page' },
+  );
+  // Nothing to show: no item, a done one, or an agent's note without a place.
+  assert.deepEqual(feedbackRevealPlan(undefined, at('src/pages/index.astro')), { kind: 'none' });
+  assert.deepEqual(feedbackRevealPlan({ ...onHome, done: true }, at('src/pages/index.astro')), {
+    kind: 'none',
+  });
+  assert.deepEqual(feedbackRevealPlan(item('agent', [], []), at('src/pages/index.astro')), {
+    kind: 'none',
+  });
+  assert.throws(
+    () => feedbackRevealPlan({ ...onHome, keys: ['nohash'] }, at('src/pages/index.astro')),
+    /names its file/,
+  );
+});
+
+test('the canvas scrolls to a pin only once its page has measured it', () => {
+  const pin = { id: 'a', path: '0.2', occurrence: 1, index: 1, note: 'Note a' };
+  const box = { x: 0, y: 900, w: 10, h: 10 };
+  const measured = { 0.2: [box, box] };
+  const ask = (overrides) =>
+    revealTarget({ revealId: 'a', pins: [pin], rects: measured, ...overrides });
+  assert.equal(ask({ stale: undefined }), pin);
+  // Its page is still opening: no pin yet.
+  assert.equal(ask({ pins: [], stale: undefined }), undefined);
+  // The previous page's rects, even with a path of the same name, do not count.
+  assert.equal(ask({ stale: measured }), undefined);
+  // The fresh page has not measured the pin yet.
+  assert.equal(ask({ rects: {}, stale: measured }), undefined);
+  assert.equal(ask({ rects: { 0.2: [] }, stale: undefined }), undefined);
+  assert.equal(ask({ rects: { ...measured }, stale: measured }), pin);
+});