@plannotator/ui 0.28.0 → 0.29.0

package/components/Settings.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useState, useEffect, useMemo, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import type { Origin } from '@plannotator/core/agents';
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
@@ -28,9 +28,11 @@ import {
 } from '../utils/octarine';
 import {
   getAgentSwitchSettings,
+  getAgentSwitchDefaults,
   saveAgentSwitchSettings,
   AGENT_OPTIONS,
   type AgentSwitchSettings,
+  type AgentSwitchSurface,
 } from '../utils/agentSwitch';
 import {
   getPlanSaveSettings,
@@ -70,8 +72,9 @@ import {
   saveFileBrowserSettings,
   type FileBrowserSettings,
 } from '../utils/fileBrowser';
+import { requestVimDocumentFocus } from '../hooks/useVimDocumentFocus';
 
-type SettingsTab = 'general' | 'theme' | 'git' | 'display' | 'saving' | 'labels' | 'shortcuts' | 'ai' | 'files' | 'obsidian' | 'bear' | 'octarine' | 'comments' | 'hooks';
+type SettingsTab = 'general' | 'theme' | 'git' | 'display' | 'saving' | 'labels' | 'vim' | 'shortcuts' | 'ai' | 'files' | 'obsidian' | 'bear' | 'octarine' | 'comments' | 'hooks';
 
 interface SettingsProps {
   taterMode: boolean;
@@ -169,23 +172,27 @@ function SegmentedControl<T extends string>({ options, value, onChange }: {
   );
 }
 
-function ToggleSwitch({ checked, onChange, label, description }: {
+function ToggleSwitch({ checked, onChange, label, description, disabled = false }: {
   checked: boolean;
   onChange: (v: boolean) => void;
   label: string;
   description?: string;
+  disabled?: boolean;
 }) {
   return (
-    <div className="flex items-center justify-between">
+    <div className={`flex items-center justify-between gap-4 ${disabled ? 'opacity-50' : ''}`}>
       <div>
         <div className="text-sm font-medium">{label}</div>
         {description && <div className="text-xs text-muted-foreground">{description}</div>}
       </div>
       <button
+        type="button"
         role="switch"
+        aria-label={label}
         aria-checked={checked}
+        disabled={disabled}
         onClick={() => onChange(!checked)}
-        className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors ${
+        className={`relative inline-flex h-6 w-11 shrink-0 items-center rounded-full transition-colors disabled:cursor-not-allowed ${
           checked ? 'bg-primary' : 'bg-muted'
         }`}
       >
@@ -199,6 +206,88 @@ function ToggleSwitch({ checked, onChange, label, description }: {
   );
 }
 
+interface VimSettingsTabProps {
+  readonly vimModeEnabled: boolean;
+  readonly vimHudEnabled: boolean;
+  readonly vimHudKeyPanelEnabled: boolean;
+  readonly onVimModeChange: (enabled: boolean) => void;
+  readonly onVimHudChange: (enabled: boolean) => void;
+  readonly onVimHudKeyPanelChange: (enabled: boolean) => void;
+}
+
+/** First-class Vim configuration, separate from the shortcut reference. */
+function VimSettingsTab({
+  vimModeEnabled,
+  vimHudEnabled,
+  vimHudKeyPanelEnabled,
+  onVimModeChange,
+  onVimHudChange,
+  onVimHudKeyPanelChange,
+}: VimSettingsTabProps) {
+  return (
+    <div className="space-y-5">
+      <div>
+        <div className="text-sm font-semibold">Vim mode</div>
+        <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+          Navigate, select, and annotate the rendered document without reaching for the mouse.
+        </p>
+      </div>
+
+      <div className="space-y-4 rounded-xl border border-border bg-muted/20 p-4">
+        <ToggleSwitch
+          checked={vimModeEnabled}
+          onChange={onVimModeChange}
+          label="Vim controls"
+          description="Use Vim-style keys for document navigation and annotation. Off by default."
+        />
+        <div className="border-t border-border" />
+        <ToggleSwitch
+          checked={vimModeEnabled && vimHudEnabled}
+          onChange={onVimHudChange}
+          label="Vim HUD"
+          description={
+            vimModeEnabled
+              ? 'Show the four-corner target reticle and navigation context.'
+              : 'Enable Vim controls first to use the target reticle.'
+          }
+          disabled={!vimModeEnabled}
+        />
+        <div className="border-t border-border" />
+        <ToggleSwitch
+          checked={vimModeEnabled && vimHudEnabled && vimHudKeyPanelEnabled}
+          onChange={onVimHudKeyPanelChange}
+          label="Key panel"
+          description={
+            vimModeEnabled && vimHudEnabled
+              ? 'Show the bottom-right live keypress legend and command panel.'
+              : 'Enable the Vim HUD first to use the live keypress legend.'
+          }
+          disabled={!vimModeEnabled || !vimHudEnabled}
+        />
+      </div>
+
+      <div className="rounded-xl border border-primary/20 bg-primary/[0.05] p-4">
+        <div className="flex items-start gap-3">
+          <span className="grid h-7 w-7 shrink-0 place-items-center rounded-md bg-primary/15 font-mono text-xs font-bold text-primary">
+            ?
+          </span>
+          <div>
+            <div className="text-xs font-semibold">Learn while you navigate</div>
+            <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+              Vim takes focus automatically when the page is ready. From other app controls, press{' '}
+              <span className="font-mono text-foreground">Esc</span> to return to the document, then
+              use <span className="font-mono text-foreground">j</span> and{' '}
+              <span className="font-mono text-foreground">k</span> to move by block. Press{' '}
+              <span className="font-mono text-foreground">?</span> for the complete key map,
+              even when the Key panel is hidden.
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 const GitTab: React.FC<{ sinceBaseUnavailable?: boolean }> = ({ sinceBaseUnavailable }) => {
   const defaultDiffType = useConfigValue('defaultDiffType');
   const reviewPanelView = useConfigValue('reviewPanelView');
@@ -278,6 +367,7 @@ const ReviewDisplayTab: React.FC = () => {
   const diffShowBackground = useConfigValue('diffShowBackground');
   const diffLineBgIntensity = useConfigValue('diffLineBgIntensity');
   const diffHideWhitespace = useConfigValue('diffHideWhitespace');
+  const editSuggestions = useConfigValue('editSuggestions');
   const diffExpandUnchanged = useConfigValue('diffExpandUnchanged');
   const diffFontFamily = useConfigValue('diffFontFamily');
   const diffFontSize = useConfigValue('diffFontSize');
@@ -289,6 +379,21 @@ const ReviewDisplayTab: React.FC = () => {
 
   return (
     <>
+      {/* Experimental: edit code to author suggestions */}
+      <div className="space-y-3">
+        <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+          Experimental
+        </div>
+        <ToggleSwitch
+          checked={editSuggestions}
+          onChange={(v) => configStore.set('editSuggestions', v)}
+          label="Edit Code to Suggest"
+          description="Edit a file in place in the all-files view; your net change becomes a suggestion comment. Files are never written from the browser. Uses an experimental upstream editor."
+        />
+      </div>
+
+      <div className="border-t border-border" />
+
       {/* Font Family */}
       <div className="space-y-2">
         <div>
@@ -443,6 +548,9 @@ const ReviewDisplayTab: React.FC = () => {
         description="Ignore whitespace-only changes in diffs"
       />
 
+      <div className="border-t border-border" />
+
+
     </>
   );
 };
@@ -653,8 +761,23 @@ const CommentsTab: React.FC = () => {
 
 export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, sinceBaseUnavailable, onDetectObsidianVaults }) => {
   const [showDialog, setShowDialog] = useState(false);
+  const settingsWasOpenRef = useRef(false);
   const [themePreview, setThemePreview] = useState(false);
 
+  useEffect(() => {
+    const wasOpen = settingsWasOpenRef.current;
+    settingsWasOpenRef.current = showDialog;
+    if (
+      wasOpen
+      && !showDialog
+      && !themePreview
+      && mode !== 'review'
+      && configStore.get('vimModeEnabled')
+    ) {
+      requestVimDocumentFocus();
+    }
+  }, [mode, showDialog, themePreview]);
+
   useEffect(() => {
     if (!themePreview) return;
     const handler = (e: KeyboardEvent) => {
@@ -665,6 +788,9 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   }, [themePreview]);
   const [activeTab, setActiveTab] = useState<SettingsTab>('general');
   const gridEnabled = useConfigValue('gridEnabled');
+  const vimModeEnabled = useConfigValue('vimModeEnabled');
+  const vimHudEnabled = useConfigValue('vimHudEnabled');
+  const vimHudKeyPanelEnabled = useConfigValue('vimHudKeyPanelEnabled');
   const [identity, setIdentity] = useState('');
   const [obsidian, setObsidian] = useState<ObsidianSettings>({
     enabled: false,
@@ -678,7 +804,10 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   const [vaultsLoading, setVaultsLoading] = useState(false);
   const [bear, setBear] = useState<BearSettings>({ enabled: false, customTags: '', tagPosition: 'append', autoSave: false });
   const [octarine, setOctarine] = useState<OctarineSettings>({ enabled: false, workspace: '', folder: 'plannotator', autoSave: false });
-  const [agent, setAgent] = useState<AgentSwitchSettings>({ switchTo: 'build' });
+  // The agent switch default depends on the surface: plan approval hands off to
+  // the build agent, review feedback stays on the current agent.
+  const agentSurface: AgentSwitchSurface = mode === 'review' ? 'review' : 'plan';
+  const [agent, setAgent] = useState<AgentSwitchSettings>(() => getAgentSwitchDefaults(agentSurface));
   const [planSave, setPlanSave] = useState<PlanSaveSettings>({ enabled: true, customPath: null });
   const [uiPrefs, setUiPrefs] = useState<UIPreferences>({ tocEnabled: true, stickyActionsEnabled: true, planWidth: 'compact' });
   const [permissionMode, setPermissionMode] = useState<PermissionMode>('bypassPermissions');
@@ -693,7 +822,7 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   const [newDirPath, setNewDirPath] = useState('');
 
   // Fetch available agents for OpenCode
-  const { agents: availableAgents, validateAgent, getAgentWarning } = useAgents(origin ?? null);
+  const { agents: availableAgents, validateAgent, getAgentWarning } = useAgents(origin ?? null, agentSurface);
 
   const mainTabs = useMemo(() => {
     const t: { id: SettingsTab; label: string }[] = [{ id: 'general', label: 'General' }];
@@ -705,12 +834,15 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
     }
     if (mode === 'review') {
       t.push({ id: 'git', label: 'Git' });
-      t.push({ id: 'display', label: 'Display' });
+      t.push({ id: 'display', label: 'Editor' });
       t.push({ id: 'comments', label: 'Comments' });
       if (aiProviders.length > 0) {
         t.push({ id: 'ai', label: 'AI' });
       }
     }
+    if (mode !== 'review') {
+      t.push({ id: 'vim', label: 'Vim' });
+    }
     t.push({ id: 'shortcuts', label: 'Shortcuts' });
     if (mode === 'plan') {
       t.push({ id: 'hooks', label: 'Hooks' });
@@ -742,7 +874,7 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
       setObsidian(getObsidianSettings());
       setBear(getBearSettings());
       setOctarine(getOctarineSettings());
-      setAgent(getAgentSwitchSettings());
+      setAgent(getAgentSwitchSettings(agentSurface));
       setPlanSave(getPlanSaveSettings());
       setUiPrefs(getUIPreferences());
       setPermissionMode(getPermissionModeSettings().mode);
@@ -914,12 +1046,23 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
         >
           <div
             className="bg-card border border-border rounded-xl w-full max-w-2xl max-h-[85vh] flex flex-col shadow-2xl relative overflow-hidden"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="plannotator-settings-title"
             onClick={e => e.stopPropagation()}
+            onKeyDown={(event) => {
+              if (event.key !== 'Escape' || event.defaultPrevented) return;
+              event.preventDefault();
+              event.stopPropagation();
+              setShowDialog(false);
+            }}
           >
             {taterMode && <TaterSpritePullup />}
             <div className="flex items-center justify-between p-4 border-b border-border">
-              <h3 className="font-semibold text-sm">Settings</h3>
+              <h3 id="plannotator-settings-title" className="font-semibold text-sm">Settings</h3>
               <button
+                type="button"
+                aria-label="Close settings"
                 onClick={() => setShowDialog(false)}
                 className="p-1.5 rounded-md bg-muted hover:bg-muted/80 text-foreground transition-colors"
               >
@@ -1655,7 +1798,11 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                                       saveQuickLabels(updated);
                                       setEditingTipIndex(null);
                                     }
-                                    if (e.key === 'Escape') setEditingTipIndex(null);
+                                    if (e.key === 'Escape') {
+                                      e.preventDefault();
+                                      e.stopPropagation();
+                                      setEditingTipIndex(null);
+                                    }
                                   }}
                                   placeholder="AI instruction tip..."
                                   className="flex-1 px-2 py-1 bg-background/60 rounded text-[10px] text-muted-foreground placeholder:text-muted-foreground/30 focus:outline-none focus:ring-1 focus:ring-primary/50"
@@ -1709,9 +1856,22 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                   </>
                 )}
 
+                {/* === VIM TAB === */}
+                {activeTab === 'vim' && mode !== 'review' && (
+                  <VimSettingsTab
+                    vimModeEnabled={vimModeEnabled}
+                    vimHudEnabled={vimHudEnabled}
+                    vimHudKeyPanelEnabled={vimHudKeyPanelEnabled}
+                    onVimModeChange={(enabled) => configStore.set('vimModeEnabled', enabled)}
+                    onVimHudChange={(enabled) => configStore.set('vimHudEnabled', enabled)}
+                    onVimHudKeyPanelChange={(enabled) =>
+                      configStore.set('vimHudKeyPanelEnabled', enabled)}
+                  />
+                )}
+
                 {/* === SHORTCUTS TAB === */}
                 {activeTab === 'shortcuts' && (
-                  <KeyboardShortcuts mode={mode} />
+                  <KeyboardShortcuts mode={mode} vimModeEnabled={vimModeEnabled} />
                 )}
 
                 {/* === COMMENTS TAB === */}

package/components/SkillReferenceMenu.tsx

@@ -0,0 +1,260 @@
+import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import type { SkillCatalogEntry } from '../utils/skillReferences';
+
+/** Which skill root a row came from, shown as the right-aligned source column. */
+const ROOT_LABELS: Record<SkillCatalogEntry['root'], string> = {
+  claude: 'Claude',
+  codex: 'Codex',
+  universal: 'Agents',
+};
+
+interface SkillReferenceMenuProps {
+  items: SkillCatalogEntry[];
+  /** Explicitly activated row, or null — the menu opens with nothing active. */
+  activeIndex: number | null;
+  onSelect: (index: number) => void;
+}
+
+/** Vertical gap between the composer wrapper and the menu (mb-1.5 / mt-1.5 = 6px). */
+const MENU_GAP = 6;
+/** Breathing room kept between the menu and the viewport edge. */
+const MENU_VIEWPORT_MARGIN = 8;
+/** Upper bound on the scrollable list height — the former fixed `max-h-64`. */
+const MAX_LIST_HEIGHT = 256;
+
+interface MenuPlacement {
+  direction: 'above' | 'below';
+  maxListHeight: number;
+}
+
+/**
+ * Adaptive placement, the same viewport-measurement idiom CommentPopover's
+ * `computePosition` uses (space vs `window.innerHeight`). The menu PREFERS
+ * opening above the composer — that keeps the text being typed, the action
+ * row, and the human-only notice unobstructed, and matches how chat-composer
+ * autocompletes behave — and flips below when the list does not fit above but
+ * does fit below (the popover near the top of the viewport: the exact case
+ * where the old fixed `bottom-full` menu ran off the top of the screen).
+ * When neither side fits the whole list, the side with more room wins and the
+ * list is clamped to it, so the menu never extends past a viewport edge.
+ */
+function computeMenuPlacement(
+  anchorRect: Pick<DOMRect, 'top' | 'bottom'>,
+  naturalListHeight: number,
+  chromeHeight: number,
+  viewportHeight: number,
+): MenuPlacement {
+  const spaceAbove = anchorRect.top - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
+  const spaceBelow = viewportHeight - anchorRect.bottom - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
+  const needed = Math.min(naturalListHeight, MAX_LIST_HEIGHT);
+  const direction: MenuPlacement['direction'] =
+    needed <= spaceAbove ? 'above'
+    : needed <= spaceBelow ? 'below'
+    : spaceAbove >= spaceBelow ? 'above'
+    : 'below';
+  const available = direction === 'above' ? spaceAbove : spaceBelow;
+  return {
+    direction,
+    maxListHeight: Math.max(0, Math.min(MAX_LIST_HEIGHT, Math.round(available))),
+  };
+}
+
+/**
+ * Dropdown for skill references inside a comment composer. Rendered adjacent
+ * to the textarea (absolute within a relative wrapper), opening above or
+ * below depending on available viewport space (see computeMenuPlacement), and
+ * clamped so it never runs off screen. Each row: icon, bold name, dimmed
+ * inline description (ellipsis-truncated), right-aligned source root.
+ * Human-invocation-only skills render identically to every other row: their
+ * instructions are injected into the exported feedback automatically, so the
+ * distinction needs no surfacing at pick time. (A hover-disclosed warning
+ * used to live here; because it changed the menu's height while the pointer
+ * sat over a row of a bottom-anchored menu, it oscillated the row under the
+ * cursor every frame. Hover must never change any row's rendered size or the
+ * menu's measured geometry — color-only hover styling is fine.)
+ *
+ * Activation is KEYBOARD-ONLY (see useSkillReferenceAutocomplete): the menu
+ * floats directly over the composer, exactly where the mouse rests while
+ * typing, so pointer hover must never arm the "Enter inserts" state. Hover is
+ * a purely visual affordance; a pointer click inserts directly.
+ */
+export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
+  items,
+  activeIndex,
+  onSelect,
+}) => {
+  const menuRef = useRef<HTMLDivElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const [placement, setPlacement] = useState<MenuPlacement>({
+    direction: 'above',
+    maxListHeight: MAX_LIST_HEIGHT,
+  });
+
+  const measure = useCallback(() => {
+    const menuEl = menuRef.current;
+    const listEl = listRef.current;
+    // The menu is a direct child of the composer's `relative` wrapper — the
+    // same box the `bottom-full` / `top-full` CSS anchors to.
+    const anchor = menuEl?.parentElement;
+    if (!menuEl || !listEl || !anchor) return;
+    const rect = anchor.getBoundingClientRect();
+    // Non-list height the menu carries (border). This must stay constant
+    // while the pointer moves — hover-dependent chrome is what caused the
+    // jitter loop this component once shipped.
+    const chrome = Math.max(0, menuEl.offsetHeight - listEl.offsetHeight);
+    // scrollHeight reports full content height even while clamped.
+    const next = computeMenuPlacement(rect, listEl.scrollHeight, chrome, window.innerHeight);
+    setPlacement((prev) =>
+      prev.direction === next.direction && prev.maxListHeight === next.maxListHeight
+        ? prev
+        : next,
+    );
+  }, []);
+
+  // Re-measure on EVERY commit: the popover re-renders on drag moves, flips,
+  // and filtering (item-count changes), and each of those can change the
+  // geometry without any window event firing. The setState above is
+  // equality-guarded, so this converges instead of looping.
+  useLayoutEffect(() => {
+    measure();
+  });
+
+  // Same listeners CommentPopover's own position tracking uses: capture-phase
+  // scroll (the document scrolls under the anchored popover) plus resize.
+  useEffect(() => {
+    window.addEventListener('scroll', measure, true);
+    window.addEventListener('resize', measure);
+    return () => {
+      window.removeEventListener('scroll', measure, true);
+      window.removeEventListener('resize', measure);
+    };
+  }, [measure]);
+
+  useEffect(() => {
+    if (activeIndex === null) return;
+    const list = listRef.current;
+    const row = list?.children[activeIndex] as HTMLElement | undefined;
+    row?.scrollIntoView({ block: 'nearest' });
+  }, [activeIndex]);
+
+  return (
+    <div
+      ref={menuRef}
+      data-skill-menu="true"
+      data-skill-menu-placement={placement.direction}
+      data-popover-layer="true"
+      className={`absolute left-0 right-0 z-[110] bg-popover border border-border rounded-xl shadow-2xl overflow-hidden ${
+        placement.direction === 'above' ? 'bottom-full mb-1.5' : 'top-full mt-1.5'
+      }`}
+    >
+      <div
+        ref={listRef}
+        data-skill-menu-list="true"
+        className="overflow-y-auto p-1.5 flex flex-col gap-px"
+        style={{ maxHeight: placement.maxListHeight }}
+      >
+        {items.map((item, index) => (
+          <button
+            key={item.name}
+            type="button"
+            data-skill-item={item.name}
+            data-skill-item-active={index === activeIndex ? 'true' : undefined}
+            // Insert on pointerdown so the textarea never loses focus. A
+            // click is explicit selection; hover deliberately does NOT
+            // activate the row (see the component docblock), and its only
+            // styling is the color-only hover:bg — hover must never change
+            // a row's rendered size or the menu's geometry.
+            onPointerDown={(e) => {
+              e.preventDefault();
+              onSelect(index);
+            }}
+            className={`w-full flex items-center gap-2.5 px-2.5 py-2 rounded-lg text-left text-[13px] leading-snug transition-colors ${
+              index === activeIndex ? 'bg-muted' : 'hover:bg-muted/50'
+            }`}
+          >
+            <SkillIcon />
+            <span className="shrink-0 font-semibold text-foreground">{item.name}</span>
+            <span className="min-w-0 flex-1 truncate text-muted-foreground">
+              {item.description ?? ''}
+            </span>
+            <span className="shrink-0 pl-3 text-xs text-muted-foreground/80">
+              {ROOT_LABELS[item.root]}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+const SkillIcon: React.FC = () => (
+  <svg
+    className="w-4 h-4 shrink-0 text-muted-foreground"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={1.7}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+    <path d="M3.29 7 12 12l8.71-5" />
+    <path d="M12 22V12" />
+  </svg>
+);
+
+interface HumanOnlySkillNoticeProps {
+  skills: SkillCatalogEntry[];
+}
+
+/**
+ * Composer note while human-only skill references are present. Quiet by
+ * design: the user already chose to insert the reference (and saw the menu's
+ * disclosure while choosing), so the resting state is a single muted summary
+ * line rather than a standing explanation. The full plain-language sentence
+ * is one native disclosure away — <details>/<summary> keeps the expansion
+ * reachable by pointer, keyboard (the summary is focusable; Enter/Space
+ * toggles), and assistive tech alike. It pairs with the dotted-underline
+ * marker the composer overlay paints on human-only tokens.
+ */
+export const HumanOnlySkillNotice: React.FC<HumanOnlySkillNoticeProps> = ({ skills }) => {
+  if (skills.length === 0) return null;
+  const names = skills.map((s) => s.name).join(', ');
+  return (
+    <details data-skill-human-only-notice="true" className="group mt-1 px-1">
+      <summary className="list-none [&::-webkit-details-marker]:hidden inline-flex cursor-pointer select-none items-center gap-1 rounded text-[10px] text-muted-foreground/80 transition-colors hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring">
+        <DisclosureChevron />
+        Includes skill instructions
+      </summary>
+      <p className="mt-0.5 pl-3.5 text-[11px] leading-snug text-muted-foreground">
+        {skills.length === 1 ? (
+          <>
+            <span className="font-mono">{names}</span> cannot be invoked by a model, so
+            its instructions will be included with your feedback.
+          </>
+        ) : (
+          <>
+            <span className="font-mono">{names}</span> cannot be invoked by a model, so
+            their instructions will be included with your feedback.
+          </>
+        )}
+      </p>
+    </details>
+  );
+};
+
+const DisclosureChevron: React.FC = () => (
+  <svg
+    className="w-2.5 h-2.5 shrink-0 transition-transform group-open:rotate-90"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m9 18 6-6-6-6" />
+  </svg>
+);

package/components/StickyHeaderLane.tsx

@@ -69,6 +69,9 @@ interface StickyHeaderLaneProps {
   isPlanDiffActive?: boolean;
   hasPreviousVersion?: boolean;
   onPlanDiffToggle?: () => void;
+  /** Baseline suffix + tooltip for the plan-diff badge (see DocBadges). */
+  planDiffBaselineLabel?: string;
+  planDiffBaselineTooltip?: string;
   archiveInfo?: { status: 'approved' | 'denied' | 'unknown'; timestamp: string; title: string } | null;
 
   // Layout
@@ -94,6 +97,8 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   isPlanDiffActive,
   hasPreviousVersion,
   onPlanDiffToggle,
+  planDiffBaselineLabel,
+  planDiffBaselineTooltip,
   archiveInfo,
   maxWidth,
   remountToken,
@@ -251,6 +256,8 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
             isPlanDiffActive={isPlanDiffActive}
             hasPreviousVersion={hasPreviousVersion}
             onPlanDiffToggle={onPlanDiffToggle}
+            planDiffBaselineLabel={planDiffBaselineLabel}
+            planDiffBaselineTooltip={planDiffBaselineTooltip}
             archiveInfo={archiveInfo}
           />
         </div>