feat(right-panel): comment mode in the Code tab, copy-to-clipboard flush

.agency/do.md

@@ -24,6 +24,7 @@ Keep these docs in sync:
 
 - **`README.md`** (top-level) — user-facing changes, architecture prose, transport-resilience description.
 - **`packages/surface/README.md`** — the `@kolu/surface` framework reference. The "How Kolu uses this framework" section is a concrete inventory of every cell, collection, and stream descriptor plus the raw-oRPC procedures that stay outside the framework. Update it whenever a new descriptor lands or whenever a contract entry's classification changes (added mutation, retired stream, …).
+- **`website/src/pages/index.astro`** — the kolu.dev landing page. Its hand-maintained `features` array (and the `NN features` count chip) must mirror the top-level `README.md`'s feature sections: when you add a `### NewThing` section to the README's Features region, add a corresponding tile to `features` and bump the chip count. The website is deployed independently (its own flake under `website/`), but treating the README and the landing page as one set keeps the public face from drifting behind the project's own description.
 
 ## PR evidence
 

README.md

@@ -154,6 +154,20 @@ Detects [OpenCode](https://github.com/anomalyco/opencode) sessions and shows the
 
 - <kbd>Ctrl+V</kbd> pastes images into any agent that accepts paste-as-file-path (Claude Code, codex, …) — the server saves the browser's clipboard image and bracketed-pastes its path into the PTY
 
+### Comments
+
+Annotate any file the agent wrote (or any file at all — code, markdown, configs) directly from the Code tab and flush the queue to your clipboard. Paste the resulting block into whichever agent terminal makes sense; no per-agent wiring, no `kolu artifact` CLI, no server-side delivery.
+
+- **Four ways to start** — 💬 chip in the Code-tab toolbar, <kbd>Cmd/Ctrl+Shift+/</kbd> keybind, command palette entry, or right-click any selected line and pick *Add comment on `path:Lrange`*. The chrome bar also surfaces a `💬 N` count badge whenever the active worktree has queued comments, so you don't have to remember the queue is there
+- **Inline composer at the line** — click a line in comment mode and a tiny composer pops up anchored next to that line (GitHub-PR style). <kbd>Enter</kbd> submits, <kbd>Shift+Enter</kbd> inserts a newline, <kbd>Esc</kbd> dismisses. No mouse trip to a bottom textbox; the popover comes to you
+- **Tray = read-only roll-up** — bottom of the Code tab lists queued comments with click-line-ref-to-jump, ✎ to edit (re-opens the inline composer prefilled), and 🗑 to drop one. The header bar paints itself with an accent fill whenever the queue is non-empty so you don't accidentally close the tab on unsynced notes
+- **File-tree decoration** — files with queued comments get a `●` badge in the Code-tab file tree (via Pierre's `renderRowDecoration`), so the queue is discoverable from the top of the tree, not just from the bottom tray
+- **Pinpoint targets** — Pierre's existing line-selection (click a line, drag for a range) drives the popover's target chip; works uniformly across browse mode and the local/branch diff modes, so `.md`, `.ts`, and any other text file all accept comments without per-kind logic
+- **Cross-file accumulation** — comments collect across every file you visit; the tray sorts by (path, startLine) so a paste reads as a coherent walk through the repo, not click order
+- **Plain Markdown clipboard payload** — flushed text is a Markdown bullet list with a code-spanned line ref per entry: `` - `path:start-end` — note ``. Agent-native format (matches `grep -n`, ripgrep, vim, VS Code, and what `claude` / `codex` / `opencode` parse for their `Read` tool) — no `L` prefix. No envelope or wrapper either: paste it raw, or prefix your own framing (`"Apply these comments:"`, `"## Review notes"`) before pasting
+- **Copy-and-clear** — "Copy to clipboard" is destructive by design (issue [#878](https://github.com/juspay/kolu/issues/878)): users want the tray empty for the next review pass once feedback has been pasted into an agent prompt
+- **Per-worktree persistence** — the in-progress queue is keyed by `repoRoot` in localStorage via `makePersisted`, so an accidental reload doesn't lose work and switching between worktree terminals shows each worktree's own tray
+
 ### Screen recording
 
 Record the Kolu tab — whole canvas or a single maximized terminal — with microphone and optional webcam PiP, straight to a local `.webm` file. Chromium-only (uses the File System Access API).

packages/client/src/App.tsx

@@ -43,6 +43,7 @@ import MobileTileView from "./MobileTileView";
 import { useRecorder } from "./recorder/useRecorder";
 import WebcamOverlay from "./recorder/WebcamOverlay";
 import RightPanelLayout from "./right-panel/RightPanelLayout";
+import { toggleCommentMode } from "./right-panel/useCommentMode";
 import { useRightPanel } from "./right-panel/useRightPanel";
 import { client } from "./wire";
 import { serverProcessId, wsStatus } from "./rpc/rpc";
@@ -214,6 +215,14 @@ const App: Component = () => {
     handleScreenshotTerminal: () => handleScreenshotTerminal(),
     toggleRightPanel: rightPanel.togglePanel,
     toggleRecordingPause: () => useRecorder().togglePause(),
+    // Opening the right panel + Code tab + ensuring the tray appears even
+    // when comments is empty puts the user one click from the composer —
+    // the keybind/palette flow doesn't make sense if mode toggles on but
+    // the tray is hidden behind the inspector panel.
+    toggleCommentMode: () => {
+      rightPanel.openCodeBrowser();
+      toggleCommentMode();
+    },
   };
 
   useShortcuts(actionContext);
@@ -468,6 +477,7 @@ const App: Component = () => {
         <ChromeBar
           status={wsStatus()}
           onOpenPalette={() => openPalette()}
+          activeRepoRoot={() => store.activeMeta()?.git?.repoRoot ?? null}
           workspaceSwitcher={
             <WorkspaceSwitcher
               entries={workspaceEntries()}

packages/client/src/ChromeBar.tsx

@@ -24,6 +24,7 @@ import { useViewPosture } from "./canvas/useViewPosture";
 import { ACTIONS } from "./input/actions";
 import { formatKeybind } from "./input/keyboard";
 import RecordButton from "./recorder/RecordButton";
+import CommentCountBadge from "./right-panel/CommentCountBadge";
 import { useRightPanel } from "./right-panel/useRightPanel";
 import type { WsStatus } from "./rpc/rpc";
 import SettingsPopover from "./settings/SettingsPopover";
@@ -44,6 +45,10 @@ const ChromeBar: Component<{
    *  ChromeBar is a layout host (logo + switcher + controls); it doesn't need
    *  to know the switcher's prop shape, just where to drop it. */
   workspaceSwitcher: JSX.Element;
+  /** Active terminal's repo root, used to scope the comments-count badge
+   *  to that worktree. Accessor so the badge re-reads when the user
+   *  switches terminals across worktrees. */
+  activeRepoRoot: () => string | null;
 }> = (props) => {
   const rightPanel = useRightPanel();
   const posture = useViewPosture();
@@ -122,6 +127,7 @@ const ChromeBar: Component<{
        *  area covered when the cluster overlaps the right panel pass
        *  clicks through; each button re-enables pointer-events-auto. */}
       <div class="flex items-center gap-2 shrink-0">
+        <CommentCountBadge activeRepoRoot={props.activeRepoRoot} />
         <RecordButton />
         <Tip
           label={`Toggle inspector (${formatKeybind(ACTIONS.toggleRightPanel.keybind)})`}

packages/client/src/commands.ts

@@ -178,6 +178,10 @@ export function createCommands(deps: CommandDeps): Accessor<PaletteCommand[]> {
         ]
       : []),
     actionPaletteCommand("toggleRightPanel", deps),
+    actionPaletteCommand("toggleCommentMode", deps, {
+      description:
+        "Open the Code tab and toggle annotation mode for clipboard-flush feedback",
+    }),
     ...(!deps.isMobile()
       ? [
           actionPaletteCommand("openWorkspaceSwitcher", deps),

packages/client/src/input/actions.ts

@@ -42,6 +42,7 @@ export interface ActionContext {
   handleScreenshotTerminal: () => void;
   toggleRightPanel: () => void;
   toggleRecordingPause: () => void;
+  toggleCommentMode: () => void;
 }
 
 interface AppActionBase {
@@ -239,6 +240,14 @@ const _ACTIONS = {
     keybind: { key: ".", code: "Period", mod: true, shift: true },
     handler: (ctx) => ctx.toggleRecordingPause(),
   },
+  toggleCommentMode: {
+    label: "Toggle comment mode",
+    // Mod+Shift+/ — slash is the universal "?" key, and Shift+? reads
+    // as "query / note?" which is the right mnemonic for "annotate."
+    // Avoids the Mod+/ chord that ShortcutsHelp owns.
+    keybind: { key: "?", code: "Slash", mod: true, shift: true },
+    handler: (ctx) => ctx.toggleCommentMode(),
+  },
 } satisfies Record<string, AppAction>;
 
 export type ActionId = keyof typeof _ACTIONS;

packages/client/src/right-panel/BrowseFileView.tsx

@@ -1,30 +1,22 @@
 /** File content viewer for the Code tab's browse mode. Subscribes to the
  *  server's live file-content stream so editor saves and branch checkouts
- *  reflect without a manual refresh. The wrapper around `@kolu/solid-pierre`'s
- *  `FileView` provides shiki-powered syntax highlighting; equality-gating
- *  the snapshot via `reconcile` (inside `useStream`'s underlying primitive)
- *  avoids stomping scroll position on no-op ticks. */
+ *  reflect without a manual refresh. The `LineSelection` controller is
+ *  owned one level up so this view and the diff view share a single
+ *  `CodeMenuFrame` wrap. */
 
-import {
-  FileView,
-  type SelectedLineRange,
-  Virtualizer,
-} from "@kolu/solid-pierre";
+import { FileView, Virtualizer } from "@kolu/solid-pierre";
 import { type Component, Match, Show, Switch } from "solid-js";
 import { toast } from "solid-sonner";
 import { pierreDiffsStyle } from "../ui/pierreTheme";
+import type { LineSelection } from "../ui/useLineSelection";
 import { app } from "../wire";
-import CodeMenuFrame from "./CodeMenuFrame";
 
 export type BrowseFileViewProps = {
   repoPath: string;
   filePath: string;
   theme: "light" | "dark";
-  /** Initial line range to highlight (and scroll to). Set when the
-   *  caller opens the file at a specific range — e.g. a terminal
-   *  `path:line` click. Goes through the line-selection controller
-   *  so the right-click "Copy path:N" menu reflects the highlight. */
-  initialSelectedLines?: SelectedLineRange | null;
+  /** Line-selection controller owned by the parent `CodeMenuFrame`. */
+  selection: LineSelection;
 };
 
 const BrowseFileView: Component<BrowseFileViewProps> = (props) => {
@@ -46,39 +38,32 @@ const BrowseFileView: Component<BrowseFileViewProps> = (props) => {
         {(fc) => (
           <>
             <Show when={fc().truncated}>
-              <div class="px-2 py-1 text-warning text-[10px] border-b border-edge bg-surface-1/30">
+              <div class="px-2 py-1 text-warning text-[10px] border-b border-edge bg-surface-1/30 shrink-0">
                 File truncated (exceeds 1 MB)
               </div>
             </Show>
-            <CodeMenuFrame
-              path={props.filePath}
-              initialSelectedLines={props.initialSelectedLines}
+            {/* `<Virtualizer>` upgrades `<FileView>` to Pierre's
+             *  `VirtualizedFile` for very large files
+             *  (#809 / #514 Phase 8). Without it, `<FileView>` uses
+             *  the vanilla `File` class — same behavior as before. */}
+            <Virtualizer
+              class="flex-1 min-h-0 overflow-auto"
+              style={pierreDiffsStyle}
             >
-              {(selection) => (
-                // `<Virtualizer>` upgrades `<FileView>` to Pierre's
-                // `VirtualizedFile` for very large files
-                // (#809 / #514 Phase 8). Without it, `<FileView>` uses
-                // the vanilla `File` class — same behavior as before.
-                <Virtualizer
-                  class="h-full w-full overflow-auto"
-                  style={pierreDiffsStyle}
-                >
-                  <FileView
-                    name={props.filePath}
-                    contents={fc().content}
-                    theme={props.theme}
-                    overflow="wrap"
-                    enableLineSelection
-                    onLineSelected={selection.handleSelect}
-                    selectedLines={selection.range()}
-                    onError={(err) =>
-                      toast.error(`File render failed: ${err.message}`)
-                    }
-                    class="w-full"
-                  />
-                </Virtualizer>
-              )}
-            </CodeMenuFrame>
+              <FileView
+                name={props.filePath}
+                contents={fc().content}
+                theme={props.theme}
+                overflow="wrap"
+                enableLineSelection
+                onLineSelected={props.selection.handleSelect}
+                selectedLines={props.selection.range()}
+                onError={(err) =>
+                  toast.error(`File render failed: ${err.message}`)
+                }
+                class="w-full"
+              />
+            </Virtualizer>
           </>
         )}
       </Match>

packages/client/src/right-panel/CodeMenuFrame.tsx

@@ -10,6 +10,7 @@ import type { Component, JSX } from "solid-js";
 import {
   CodeContextMenu,
   type CodeContextMenuController,
+  type CodeContextMenuItem,
 } from "../ui/CodeContextMenu";
 import { type LineSelection, useLineSelection } from "../ui/useLineSelection";
 
@@ -25,20 +26,29 @@ export type CodeMenuFrameProps = {
    *  controller so a terminal `path:line` click drives both the
    *  Pierre highlight AND the right-click menu's "Copy path:N" item. */
   initialSelectedLines?: SelectedLineRange | null;
+  /** Forward selection changes to a parent (e.g. CodeTab's comments
+   *  tray composer). Fires on every commit, including null. */
+  onSelectionChange?: (range: SelectedLineRange | null) => void;
+  /** Extra context-menu items contributed by the caller — appended
+   *  after the built-in "Copy path" / "Copy path:N" entries. Receives
+   *  the current selection range (null when nothing is selected). */
+  extraMenuItems?: (range: SelectedLineRange | null) => CodeContextMenuItem[];
 };
 
 export const CodeMenuFrame: Component<CodeMenuFrameProps> = (props) => {
   let menuCtrl: CodeContextMenuController | undefined;
   const selection = useLineSelection(() => props.path, {
     initialRange: () => props.initialSelectedLines,
+    onChange: (range) => props.onSelectionChange?.(range),
+    extraItems: (range) => props.extraMenuItems?.(range) ?? [],
   });
   return (
     <div
       // Attach contextmenu via addEventListener so the host div doesn't
       // carry interactive JSX props — the inner Pierre canvas is the
       // actual interactive surface; the host is layout only.
       ref={(el) => el.addEventListener("contextmenu", (e) => menuCtrl?.open(e))}
-      class="h-full w-full"
+      class="flex flex-col h-full w-full"
     >
       {props.children(selection)}
       <CodeContextMenu