diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2d3884..800821d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,34 @@ All notable changes to `@cofoundy/ui` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] — 2026-05-22
+
+### Added
+
+- **`CommandPalette`** + **`CommandPaletteTrigger`** — generalized vault/search palette, extracted from `docs-ai-vault-search` and reshaped for shared consumption. Props-driven (`searchFn`, `onNavigate`, `recents`, `recentSearches`, `emptyActions`), brand-themed via the existing `--cf-*` CSS variables (with safe `:where(...)` fallbacks for standalone use), and shipped with two themes (light/dark) + a mobile bottom-sheet variant.
+- **`useCommandPaletteHotkeys`** — minimal hook that binds the canonical `Cmd+K` / `Ctrl+K`, `/`, and `Esc` keys to a controlled `open` state. Respects `INPUT`/`TEXTAREA`/`contenteditable` so native typeahead and prose editing keep working.
+- Types: `CommandPaletteProps`, `CommandPaletteTriggerProps`, `SearchHit`, `SearchResponse`, `SearchFn`, `DocRole`, `RecentDoc`, `RecentSearch`, `EmptyAction`.
+- Telemetry hooks: `onSearch?(query, hits, took_ms?)` and `onSelect?(hit, idx, source: 'click' | 'enter')` — consumer-level analytics without wrapping `searchFn`.
+
+### Safety + a11y
+
+- Snippet HTML is sanitized by default (allow-only `<mark>`); consumers with trusted backends opt in via `trustSnippetHtml`.
+- External-origin hits open in a new tab with `rel="noopener noreferrer"` automatically.
+- Focus trap on the dialog; `aria-controls` only references the listbox when mounted; option IDs namespaced via `useId` to prevent collisions between parallel instances; focus restore guarded by `isConnected`; full `prefers-reduced-motion` fallback.
+
+### Performance
+
+- Singleton CSS injection (`<style id="cp-styles">` appended once to `<head>`) — no per-mount re-parse.
+- Refcounted body scroll-lock — composes safely with sibling modals.
+- `minQueryLength` prop (default 2) + stale-results indicator during debounce — fewer wasted fetches, clearer typing feedback.
+
+### Notes
+
+- `SearchHit.role` is now optional; when present it renders as a small role badge next to the title.
+- Trigger pill's 44×44 minimum hit target is gated behind `@media (pointer: coarse)` so desktop keeps the visually-designed 32px height.
+
+Files: `src/components/command-palette/CommandPalette.tsx`, `src/__tests__/components/command-palette/CommandPalette.test.tsx` (21 tests), `src/stories/command-palette/CommandPalette.stories.tsx`, `src/index.ts` (new public exports).
+
 ## [0.5.3] — 2026-05-20
 
 ### Fixed
diff --git a/package.json b/package.json
index 6011f3a..76e9709 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cofoundy/ui",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "private": true,
   "type": "module",
   "main": "./src/index.ts",
diff --git a/src/__tests__/components/command-palette/CommandPalette.test.tsx b/src/__tests__/components/command-palette/CommandPalette.test.tsx
index 7c26617..e1092da 100644
--- a/src/__tests__/components/command-palette/CommandPalette.test.tsx
+++ b/src/__tests__/components/command-palette/CommandPalette.test.tsx
@@ -1,11 +1,14 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
 import { useState } from 'react';
 import {
   CommandPalette,
+  useCommandPaletteHotkeys,
   type SearchHit,
   type SearchResponse,
   type SearchFn,
+  type EmptyAction,
+  type RecentDoc,
 } from '../../../components/command-palette/CommandPalette';
 
 const FIXTURE: SearchHit[] = [
@@ -54,6 +57,7 @@ function Harness({
       onNavigate={onNavigate}
       scope="team"
       debounceMs={0}
+      minQueryLength={1}
     />
   );
 }
@@ -129,4 +133,259 @@ describe('CommandPalette', () => {
       expect(screen.queryByRole('dialog', { name: /search documentation/i })).toBeNull(),
     );
   });
+
+  it('does not fire searchFn for sub-minQueryLength queries', async () => {
+    const searchFn = vi.fn(instant(FIXTURE));
+    function GatedHarness() {
+      const [open, setOpen] = useState(true);
+      return (
+        <CommandPalette
+          open={open}
+          onOpenChange={setOpen}
+          searchFn={searchFn}
+          scope="team"
+          debounceMs={0}
+          minQueryLength={3}
+        />
+      );
+    }
+    render(<GatedHarness />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'ab' } });
+    await waitFor(() =>
+      expect(screen.queryByText(/start typing to search the vault/i)).toBeTruthy(),
+    );
+    expect(searchFn).not.toHaveBeenCalled();
+  });
+
+  it('sanitizes <script> out of snippet HTML by default', async () => {
+    const dangerous: SearchHit = {
+      project: 'p',
+      slug: 's',
+      role: 'team',
+      title: 'Dangerous',
+      snippet: 'hello <script>alert(1)</script> <mark>world</mark>',
+      score: 0,
+      url: '/x',
+    };
+    render(<Harness searchFn={instant([dangerous])} />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'hello' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    const snippet = document.querySelector('.cp-result-snippet');
+    expect(snippet?.innerHTML.includes('<script>')).toBe(false);
+    expect(snippet?.innerHTML.includes('<mark>world</mark>')).toBe(true);
+  });
+
+  it('preserves raw snippet HTML when trustSnippetHtml is true', async () => {
+    const trusted: SearchHit = {
+      project: 'p',
+      slug: 's',
+      role: 'team',
+      title: 'Trusted',
+      snippet: '<mark>kept</mark> <em>and emphasized</em>',
+      score: 0,
+      url: '/x',
+    };
+    function TrustingHarness() {
+      const [open, setOpen] = useState(true);
+      return (
+        <CommandPalette
+          open={open}
+          onOpenChange={setOpen}
+          searchFn={instant([trusted])}
+          scope="team"
+          debounceMs={0}
+          minQueryLength={1}
+          trustSnippetHtml
+        />
+      );
+    }
+    render(<TrustingHarness />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'kept' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    const snippet = document.querySelector('.cp-result-snippet');
+    expect(snippet?.innerHTML.includes('<em>and emphasized</em>')).toBe(true);
+  });
+
+  it('clear button empties the query and refocuses input', async () => {
+    render(<Harness searchFn={instant(FIXTURE)} />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'brand' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    const clearBtn = screen.getByLabelText(/clear search/i);
+    fireEvent.click(clearBtn);
+    expect(input.value).toBe('');
+  });
+
+  it('fires onSearch + onSelect telemetry callbacks', async () => {
+    const onSearch = vi.fn();
+    const onSelect = vi.fn();
+    function TelemetryHarness() {
+      const [open, setOpen] = useState(true);
+      return (
+        <CommandPalette
+          open={open}
+          onOpenChange={setOpen}
+          searchFn={instant(FIXTURE)}
+          onNavigate={() => {}}
+          onSearch={onSearch}
+          onSelect={onSelect}
+          scope="team"
+          debounceMs={0}
+          minQueryLength={1}
+        />
+      );
+    }
+    render(<TelemetryHarness />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'brand' } });
+    await waitFor(() => expect(onSearch).toHaveBeenCalled());
+    expect(onSearch).toHaveBeenCalledWith('brand', expect.any(Array), 1);
+    fireEvent.keyDown(input, { key: 'Enter' });
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({ title: 'Brand Validator' }),
+      0,
+      'enter',
+    );
+  });
+
+  it('emptyActions chip with onSelect fires when clicked', async () => {
+    const onChip = vi.fn();
+    const actions: EmptyAction[] = [{ label: 'Switch scope', kbd: '2', onSelect: onChip }];
+    function EmptyHarness() {
+      const [open, setOpen] = useState(true);
+      return (
+        <CommandPalette
+          open={open}
+          onOpenChange={setOpen}
+          searchFn={instant([])}
+          scope="team"
+          debounceMs={0}
+          minQueryLength={1}
+          emptyActions={actions}
+        />
+      );
+    }
+    render(<EmptyHarness />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'nothing' } });
+    const chip = await screen.findByRole('button', { name: /switch scope/i });
+    fireEvent.click(chip);
+    expect(onChip).toHaveBeenCalled();
+  });
+
+  it('Cmd+Enter on a hit opens in a new tab via window.open', async () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    const onNavigate = vi.fn();
+    render(<Harness searchFn={instant(FIXTURE)} onNavigate={onNavigate} />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'brand' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    fireEvent.keyDown(input, { key: 'Enter', metaKey: true });
+    expect(openSpy).toHaveBeenCalledWith('/team/a/one', '_blank', 'noopener,noreferrer');
+    expect(onNavigate).not.toHaveBeenCalled();
+    openSpy.mockRestore();
+  });
+
+  it('renders the role badge when SearchHit.role is set', async () => {
+    render(<Harness searchFn={instant(FIXTURE)} />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'brand' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    const badges = document.querySelectorAll('.cp-result-role');
+    expect(badges.length).toBeGreaterThan(0);
+    expect(badges[0].getAttribute('data-role')).toBe('team');
+  });
+
+  it('recents are clickable links when supplied', async () => {
+    const recents: RecentDoc[] = [
+      { title: 'Recent A', path: 'vault/a.md', date: '2d ago', url: '/team/a/recent' },
+    ];
+    function RecentHarness() {
+      const [open, setOpen] = useState(true);
+      return (
+        <CommandPalette
+          open={open}
+          onOpenChange={setOpen}
+          searchFn={instant(FIXTURE)}
+          scope="team"
+          debounceMs={0}
+          minQueryLength={1}
+          recents={recents}
+        />
+      );
+    }
+    render(<RecentHarness />);
+    const link = await screen.findByText('Recent A');
+    const anchor = link.closest('a');
+    expect(anchor?.getAttribute('href')).toBe('/team/a/recent');
+  });
+
+  it('options namespace IDs so two palettes do not collide', async () => {
+    function DualHarness() {
+      return (
+        <>
+          <CommandPalette
+            open
+            onOpenChange={() => {}}
+            searchFn={instant(FIXTURE)}
+            scope="team"
+            debounceMs={0}
+            minQueryLength={1}
+          />
+        </>
+      );
+    }
+    render(<DualHarness />);
+    const input = screen.getByLabelText(/search query/i) as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'brand' } });
+    await waitFor(() => expect(screen.getByRole('listbox')).toBeTruthy());
+    const options = document.querySelectorAll('[role="option"]');
+    for (const opt of options) {
+      expect(opt.id).toMatch(/^cp-opt-.+-\d+$/);
+    }
+  });
+
+  it('warns to console when opened without a searchFn (dev mode)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Harness />);
+    expect(warn).toHaveBeenCalledWith(expect.stringMatching(/without a `searchFn`/));
+    warn.mockRestore();
+  });
+});
+
+describe('useCommandPaletteHotkeys', () => {
+  function HookHarness({ initialOpen = false }: { initialOpen?: boolean }) {
+    const [open, setOpen] = useState(initialOpen);
+    useCommandPaletteHotkeys({ open, setOpen });
+    return <div data-testid="status">{open ? 'open' : 'closed'}</div>;
+  }
+
+  it('Cmd+K opens the palette', () => {
+    render(<HookHarness />);
+    expect(screen.getByTestId('status').textContent).toBe('closed');
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', metaKey: true }));
+    });
+    expect(screen.getByTestId('status').textContent).toBe('open');
+  });
+
+  it('Slash opens the palette when no input is focused', () => {
+    render(<HookHarness />);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: '/' }));
+    });
+    expect(screen.getByTestId('status').textContent).toBe('open');
+  });
+
+  it('Escape closes the palette when open', () => {
+    render(<HookHarness initialOpen />);
+    expect(screen.getByTestId('status').textContent).toBe('open');
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+    });
+    expect(screen.getByTestId('status').textContent).toBe('closed');
+  });
 });
diff --git a/src/components/command-palette/CommandPalette.tsx b/src/components/command-palette/CommandPalette.tsx
index fd4fdec..a8f8042 100644
--- a/src/components/command-palette/CommandPalette.tsx
+++ b/src/components/command-palette/CommandPalette.tsx
@@ -31,7 +31,12 @@ export interface SearchHit {
   project: string;
   slug: string;
   title: string;
-  role: DocRole;
+  /**
+   * Doc role taxonomy (team/client/public/custom). Optional — rendered as a
+   * small badge next to the title when present. Consumers can omit when their
+   * vault has no role concept.
+   */
+  role?: DocRole;
   /** FTS5 snippet() output — HTML-escaped except for `<mark>` wrapper. */
   snippet: string;
   /** BM25 rank — lower is better. */
@@ -65,8 +70,15 @@ export interface RecentSearch {
 
 export interface EmptyAction {
   label: string;
-  /** Single-key hint shown as a kbd chip, e.g. "1", "I". */
+  /**
+   * Single-key hint shown as a kbd chip, e.g. "1", "I". Decorative only —
+   * the library does not bind global single-character keys from the search
+   * input (would conflict with typing). Consumers needing keyboard activation
+   * should attach their own listener at the document level.
+   */
   kbd?: string;
+  /** Click/Enter handler. The chip is rendered as a button when supplied. */
+  onSelect?: () => void;
 }
 
 export interface CommandPaletteProps {
@@ -87,6 +99,12 @@ export interface CommandPaletteProps {
   mobileVariant?: 'auto' | 'modal' | 'sheet';
   /** Debounce in ms before firing searchFn. Default 200. */
   debounceMs?: number;
+  /**
+   * Minimum query length before the palette fires `searchFn`. Sub-min queries
+   * render the idle state instead of firing the backend or showing a stale
+   * "no matches" empty state. Default 2.
+   */
+  minQueryLength?: number;
   /** Input placeholder. Default 'Search docs, briefs, notes…'. */
   placeholder?: string;
   /** Idle-state recent docs list. Empty by default. */
@@ -95,6 +113,25 @@ export interface CommandPaletteProps {
   recentSearches?: RecentSearch[];
   /** No-results action chips. Empty by default. */
   emptyActions?: EmptyAction[];
+  /**
+   * Pass `true` to render `hit.snippet` as raw HTML via `dangerouslySetInnerHTML`.
+   * Default `false`: the palette runs the snippet through an allow-only-`<mark>`
+   * sanitizer that strips every other tag. Only opt in when your backend is
+   * trusted (e.g. you control the search index and emit FTS5 snippets directly).
+   */
+  trustSnippetHtml?: boolean;
+  /**
+   * Fires after each successful fetch. Lets consumers wire analytics without
+   * wrapping `searchFn`. Not called for sub-min queries (those skip the fetch
+   * entirely) or aborted requests.
+   */
+  onSearch?: (query: string, hits: SearchHit[], took_ms?: number) => void;
+  /**
+   * Fires before `onNavigate` when the user selects a hit. `source` indicates
+   * how the selection happened — useful for distinguishing keyboard-only users
+   * from mouse-only users in analytics.
+   */
+  onSelect?: (hit: SearchHit, idx: number, source: 'click' | 'enter') => void;
 }
 
 export interface CommandPaletteTriggerProps {
@@ -141,10 +178,131 @@ export function CommandPaletteTrigger({
   );
 }
 
+// ─── Hotkeys hook ─────────────────────────────────────────────────────────────
+
+/**
+ * Bind the canonical command-palette hotkeys (`Cmd+K` / `Ctrl+K`, `/`, `Esc`)
+ * to a controlled `open` state. Consumers wire it once next to their palette
+ * mount so the global keys work even when the modal is closed.
+ *
+ * Behaviour matches docs-ai-vault-search architecture §5.2:
+ *   - `Cmd+K` / `Ctrl+K` opens; suppressed only inside contenteditable.
+ *   - `/` opens, but only when no INPUT/TEXTAREA/contenteditable is focused
+ *     (so native typeahead inside form fields keeps working).
+ *   - `Esc` closes when open.
+ */
+export function useCommandPaletteHotkeys({
+  open,
+  setOpen,
+}: {
+  open: boolean;
+  setOpen: (v: boolean) => void;
+}): void {
+  useEffect(() => {
+    function onKey(e: KeyboardEvent): void {
+      if (e.key === 'Escape') {
+        if (open) {
+          e.preventDefault();
+          setOpen(false);
+        }
+        return;
+      }
+      const target = (e.target ?? null) as HTMLElement | null;
+      const tag = target?.tagName;
+      const inInputOrTextarea = tag === 'INPUT' || tag === 'TEXTAREA';
+      const inContentEditable = target?.isContentEditable === true;
+      if ((e.metaKey || e.ctrlKey) && (e.key === 'k' || e.key === 'K')) {
+        if (inContentEditable) return;
+        e.preventDefault();
+        setOpen(true);
+        return;
+      }
+      if (e.key === '/' && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        if (inInputOrTextarea || inContentEditable) return;
+        if (open) return;
+        e.preventDefault();
+        setOpen(true);
+      }
+    }
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, setOpen]);
+}
+
+// ─── Module-scope CSS injection + scroll-lock refcount ────────────────────────
+
+/**
+ * The component used to inject its CSS via `<style dangerouslySetInnerHTML>`
+ * inside the portal — every Cmd+K re-parsed the rules, two parallel instances
+ * duplicated them. Now we append a singleton `<style id="cp-styles">` to
+ * `<head>` on first mount and reuse it forever.
+ */
+let stylesInjected = false;
+function ensureCommandPaletteStyles() {
+  if (stylesInjected || typeof document === 'undefined') return;
+  if (document.getElementById('cp-styles')) {
+    stylesInjected = true;
+    return;
+  }
+  const el = document.createElement('style');
+  el.id = 'cp-styles';
+  el.textContent = COMMAND_PALETTE_CSS;
+  document.head.appendChild(el);
+  stylesInjected = true;
+}
+
+/**
+ * Body scroll-lock counter. Composes safely with sibling modals — the lock
+ * is applied only on the 0→1 transition and released only on 1→0, so closing
+ * one modal while another is still open doesn't restore body scroll prematurely.
+ */
+let scrollLockCount = 0;
+let prevBodyOverflow = '';
+function acquireBodyScrollLock() {
+  if (typeof document === 'undefined') return;
+  if (scrollLockCount === 0) {
+    prevBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+  }
+  scrollLockCount += 1;
+}
+function releaseBodyScrollLock() {
+  if (typeof document === 'undefined') return;
+  scrollLockCount = Math.max(0, scrollLockCount - 1);
+  if (scrollLockCount === 0) {
+    document.body.style.overflow = prevBodyOverflow;
+  }
+}
+
 // ─── Main palette ─────────────────────────────────────────────────────────────
 
 const DEFAULT_DEBOUNCE = 200;
 
+/**
+ * `true` when `url` resolves to a different origin than the current page.
+ * Returns `false` in SSR (no `window`) so server-rendered markup is stable.
+ * Relative URLs and malformed inputs are treated as same-origin (safe default).
+ */
+function isExternalUrl(url: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return new URL(url, window.location.origin).origin !== window.location.origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sanitize an FTS5 snippet so only `<mark>` survives. Drops any other tags
+ * (incl. attributes) and leaves text content as-is. The backend is expected
+ * to have HTML-escaped &/</> already; this is a defense-in-depth pass for
+ * library consumers wiring untrusted backends. Opt out via `trustSnippetHtml`.
+ */
+function sanitizeSnippetHtml(snippet: string): string {
+  // Strip every tag except `<mark>` / `</mark>` (case-insensitive, no attrs).
+  return snippet.replace(/<(?!\/?mark>)[^>]*>/gi, '');
+}
+
 export function CommandPalette({
   open,
   onOpenChange,
@@ -154,33 +312,73 @@ export function CommandPalette({
   project,
   mobileVariant = 'auto',
   debounceMs = DEFAULT_DEBOUNCE,
+  minQueryLength = 2,
   placeholder = 'Search docs, briefs, notes…',
   recents = [],
   recentSearches = [],
   emptyActions = [],
+  trustSnippetHtml = false,
+  onSearch,
+  onSelect,
 }: CommandPaletteProps) {
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<SearchHit[]>([]);
   const [loading, setLoading] = useState(false);
   const [errored, setErrored] = useState(false);
   const [selectedIndex, setSelectedIndex] = useState(0);
+  // `stale` covers the window between a query change and the next fetch
+  // resolving — the previous results are still on screen but no longer
+  // reflect the input. PaletteSurface dims them via [data-stale].
+  const [stale, setStale] = useState(false);
+  // Bump to force the search effect to re-fire for the same query (retry on
+  // error). `setQuery(query)` is a no-op because React bails on equal state.
+  const [retryNonce, setRetryNonce] = useState(0);
+
+  // Dev-only warning if the palette is mounted without a fetcher. Silent
+  // breakage is worse than a console line that points at the missing prop.
+  useEffect(() => {
+    if (open && !searchFn && process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[@cofoundy/ui] <CommandPalette> opened without a `searchFn` prop — ' +
+          'typing will not surface any results. Pass `searchFn` to wire a backend.',
+      );
+    }
+  }, [open, searchFn]);
 
   // Debounced fetch
   useEffect(() => {
     if (!open || !searchFn) return;
-    setErrored(false);
+    const trimmed = query.trim();
+
+    // Below the min-query threshold: clear results, surface the idle state,
+    // do not fire the backend (saves bandwidth + avoids "no matches for a").
+    if (trimmed.length < minQueryLength) {
+      setResults([]);
+      setErrored(false);
+      setLoading(false);
+      setStale(false);
+      return;
+    }
+
+    setStale(true);
     const controller = new AbortController();
     const t = setTimeout(async () => {
       setLoading(true);
+      setErrored(false);
       try {
-        const response = await searchFn(query, controller.signal);
+        const response = await searchFn(trimmed, controller.signal);
         if (controller.signal.aborted) return;
-        setResults(Array.isArray(response?.hits) ? response.hits : []);
+        const hits = Array.isArray(response?.hits) ? response.hits : [];
+        setResults(hits);
         setSelectedIndex(0);
+        setStale(false);
+        onSearch?.(trimmed, hits, response?.took_ms);
       } catch {
         if (!controller.signal.aborted) {
           setErrored(true);
           setResults([]);
+          setStale(false);
         }
       } finally {
         if (!controller.signal.aborted) setLoading(false);
@@ -190,10 +388,30 @@ export function CommandPalette({
       clearTimeout(t);
       controller.abort();
     };
-  }, [query, open, searchFn, debounceMs]);
+  }, [query, open, searchFn, debounceMs, minQueryLength, retryNonce, onSearch]);
+
+  // Reset transient state when the palette closes. Matches the docs-ai
+  // useCommandPalette hook teardown (use-command-palette.ts §setOpen) so
+  // reopening starts clean instead of showing stale query + results.
+  useEffect(() => {
+    if (!open) {
+      setQuery('');
+      setResults([]);
+      setLoading(false);
+      setErrored(false);
+      setSelectedIndex(0);
+      setStale(false);
+    }
+  }, [open]);
 
   const handleNavigate = useCallback(
     (hit: SearchHit) => {
+      // External URLs always escape to a new tab regardless of onNavigate —
+      // a consumer's router can't safely handle cross-origin nav anyway.
+      if (isExternalUrl(hit.url) && typeof window !== 'undefined') {
+        window.open(hit.url, '_blank', 'noopener,noreferrer');
+        return;
+      }
       if (onNavigate) {
         onNavigate(hit.url, hit);
       } else if (typeof window !== 'undefined') {
@@ -211,11 +429,14 @@ export function CommandPalette({
       results={results}
       loading={loading}
       errored={errored}
-      onRetry={() => setQuery((q) => q)}
+      stale={stale}
+      minQueryLength={minQueryLength}
+      onRetry={() => setRetryNonce((n) => n + 1)}
       selectedIndex={selectedIndex}
       setSelectedIndex={setSelectedIndex}
       onClose={() => onOpenChange(false)}
       onNavigate={handleNavigate}
+      onSelect={onSelect}
       scope={scope}
       project={project}
       mobileVariant={mobileVariant}
@@ -223,6 +444,7 @@ export function CommandPalette({
       recents={recents}
       recentSearches={recentSearches}
       emptyActions={emptyActions}
+      trustSnippetHtml={trustSnippetHtml}
     />
   );
 }
@@ -236,6 +458,8 @@ interface PaletteSurfaceProps {
   results: SearchHit[];
   loading: boolean;
   errored: boolean;
+  stale: boolean;
+  minQueryLength: number;
   onRetry: () => void;
   selectedIndex: number;
   setSelectedIndex: (n: number) => void;
@@ -248,6 +472,8 @@ interface PaletteSurfaceProps {
   recents: RecentDoc[];
   recentSearches: RecentSearch[];
   emptyActions: EmptyAction[];
+  trustSnippetHtml: boolean;
+  onSelect?: (hit: SearchHit, idx: number, source: 'click' | 'enter') => void;
 }
 
 function PaletteSurface({
@@ -257,6 +483,8 @@ function PaletteSurface({
   results,
   loading,
   errored,
+  stale,
+  minQueryLength,
   onRetry,
   selectedIndex,
   setSelectedIndex,
@@ -269,17 +497,22 @@ function PaletteSurface({
   recents,
   recentSearches,
   emptyActions,
+  trustSnippetHtml,
+  onSelect,
 }: PaletteSurfaceProps) {
   const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement>(null);
+  const surfaceRef = useRef<HTMLDivElement>(null);
   const lastFocusRef = useRef<HTMLElement | null>(null);
   const reactId = useId();
   const listboxId = `cp-listbox-${reactId}`;
 
   // Portal mount guard — overlay must render into document.body so backdrop-filter
   // ancestors don't pin position:fixed children to a stale containing block.
+  // Also inject the singleton stylesheet on first mount (T23).
   const [portalReady, setPortalReady] = useState(false);
   useEffect(() => {
+    ensureCommandPaletteStyles();
     setPortalReady(true);
   }, []);
 
@@ -290,19 +523,50 @@ function PaletteSurface({
       const t = setTimeout(() => inputRef.current?.focus(), 0);
       return () => clearTimeout(t);
     } else {
-      lastFocusRef.current?.focus();
+      // Only restore focus if the prior element is still in the document —
+      // route changes / sidebar collapses can unmount the trigger while the
+      // palette is open, and `.focus()` on a detached node is a silent no-op
+      // (or throws on legacy WebKit).
+      const last = lastFocusRef.current;
+      if (last && last.isConnected) last.focus();
     }
   }, [open]);
 
   useEffect(() => {
     if (!open) return;
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
+    acquireBodyScrollLock();
     return () => {
-      document.body.style.overflow = prev;
+      releaseBodyScrollLock();
     };
   }, [open]);
 
+  // Focus trap — keep Tab cycling inside the dialog. role="dialog"
+  // aria-modal="true" promises modality; the markup has to enforce it.
+  useEffect(() => {
+    if (!open) return;
+    function onTab(e: KeyboardEvent) {
+      if (e.key !== 'Tab') return;
+      const root = surfaceRef.current;
+      if (!root) return;
+      const focusable = root.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      );
+      if (focusable.length === 0) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      const active = document.activeElement as HTMLElement | null;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+    document.addEventListener('keydown', onTab);
+    return () => document.removeEventListener('keydown', onTab);
+  }, [open]);
+
   const onInputKey = useCallback(
     (e: ReactKeyboardEvent<HTMLInputElement>) => {
       if (e.key === 'Escape') {
@@ -318,6 +582,12 @@ function PaletteSurface({
         const hit = results[selectedIndex];
         if (hit) {
           e.preventDefault();
+          onSelect?.(hit, selectedIndex, 'enter');
+          // Cmd/Ctrl + Enter → open in a new tab without leaving the palette.
+          if ((e.metaKey || e.ctrlKey) && typeof window !== 'undefined') {
+            window.open(hit.url, '_blank', 'noopener,noreferrer');
+            return;
+          }
           onNavigate(hit);
         }
       } else if (e.key === 'Home') {
@@ -328,7 +598,7 @@ function PaletteSurface({
         setSelectedIndex(Math.max(0, results.length - 1));
       }
     },
-    [results, selectedIndex, setSelectedIndex, onClose, onNavigate],
+    [results, selectedIndex, setSelectedIndex, onClose, onNavigate, onSelect],
   );
 
   useEffect(() => {
@@ -342,10 +612,14 @@ function PaletteSurface({
   if (!portalReady) return null;
 
   const isSheet = mobileVariant === 'sheet';
+  const trimmedLength = query.trim().length;
+  // showEmpty fires only when we actually ran a search (query >= min) and it
+  // returned no hits. Below-min queries fall into showInitial so the user
+  // doesn't see a misleading "No matches for `a`" before the search runs.
   const showEmpty =
-    !loading && !errored && results.length === 0 && query.trim().length > 0;
+    !loading && !errored && results.length === 0 && trimmedLength >= minQueryLength;
   const showInitial =
-    !loading && !errored && results.length === 0 && query.trim().length === 0;
+    !loading && !errored && results.length === 0 && trimmedLength < minQueryLength;
 
   return createPortal(
     <div
@@ -356,6 +630,7 @@ function PaletteSurface({
       data-mobile-variant={mobileVariant}
     >
       <div
+        ref={surfaceRef}
         role="dialog"
         aria-modal="true"
         aria-label="Search documentation"
@@ -387,9 +662,11 @@ function PaletteSurface({
             onKeyDown={onInputKey}
             placeholder={placeholder}
             aria-label="Search query"
-            aria-controls={listboxId}
+            // aria-controls only references the listbox when it's mounted.
+            // Pointing at a non-existent element confuses screen readers.
+            aria-controls={results.length > 0 ? listboxId : undefined}
             aria-activedescendant={
-              results[selectedIndex] ? `cp-opt-${selectedIndex}` : undefined
+              results[selectedIndex] ? `cp-opt-${reactId}-${selectedIndex}` : undefined
             }
             aria-autocomplete="list"
             className="cp-input"
@@ -397,9 +674,36 @@ function PaletteSurface({
             autoCorrect="off"
             spellCheck={false}
           />
+          {query.length > 0 && (
+            <button
+              type="button"
+              className="cp-input-clear"
+              aria-label="Clear search"
+              onClick={() => {
+                setQuery('');
+                inputRef.current?.focus();
+              }}
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden
+                focusable="false"
+              >
+                <path d="M18 6 6 18" />
+                <path d="m6 6 12 12" />
+              </svg>
+            </button>
+          )}
         </div>
 
-        <div className="cp-results-wrap">
+        <div className="cp-results-wrap" data-stale={stale ? '' : undefined}>
           {loading && <SkeletonRows />}
           {errored && <ErrorState onRetry={onRetry} />}
           {showInitial && <InitialState recents={recents} />}
@@ -427,6 +731,7 @@ function PaletteSurface({
               >
                 {results.map((hit, i) => {
                   const selected = i === selectedIndex;
+                  const external = isExternalUrl(hit.url);
                   const breadcrumb = hit.url
                     .replace(/^\/+/, '')
                     .replace(/\/[^/]+$/, '')
@@ -434,16 +739,23 @@ function PaletteSurface({
                   return (
                     <li key={`${hit.project}/${hit.slug}`} role="presentation">
                       <a
-                        id={`cp-opt-${i}`}
+                        id={`cp-opt-${reactId}-${i}`}
                         href={hit.url}
+                        target={external ? '_blank' : undefined}
+                        rel={external ? 'noopener noreferrer' : undefined}
                         role="option"
                         aria-selected={selected}
                         data-cp-index={i}
                         data-selected={selected ? '' : undefined}
                         className="cp-result"
-                        onMouseEnter={() => setSelectedIndex(i)}
                         onClick={(e) => {
+                          // Let Cmd/Ctrl-click open in a new tab (browser default).
+                          if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+                            onSelect?.(hit, i, 'click');
+                            return;
+                          }
                           e.preventDefault();
+                          onSelect?.(hit, i, 'click');
                           onNavigate(hit);
                           onClose();
                         }}
@@ -465,13 +777,23 @@ function PaletteSurface({
                           <path d="M14 2v6h6" />
                         </svg>
                         <div className="cp-result-main">
-                          <div className="cp-result-title">{hit.title}</div>
+                          <div className="cp-result-title">
+                            <span className="cp-result-title-text">{hit.title}</span>
+                            {hit.role && (
+                              <span className="cp-result-role" data-role={hit.role}>
+                                {hit.role}
+                              </span>
+                            )}
+                          </div>
                           <div className="cp-result-path">{breadcrumb}</div>
                           {hit.snippet && (
                             <div
                               className="cp-result-snippet"
-                              // Snippet HTML is server-escaped except for <mark>.
-                              dangerouslySetInnerHTML={{ __html: hit.snippet }}
+                              dangerouslySetInnerHTML={{
+                                __html: trustSnippetHtml
+                                  ? hit.snippet
+                                  : sanitizeSnippetHtml(hit.snippet),
+                              }}
                             />
                           )}
                         </div>
@@ -521,8 +843,6 @@ function PaletteSurface({
           )}
         </div>
       </div>
-
-      <style dangerouslySetInnerHTML={{ __html: COMMAND_PALETTE_CSS }} />
     </div>,
     document.body,
   );
@@ -566,9 +886,7 @@ function InitialState({ recents }: { recents: RecentDoc[] }) {
           <li key={`${row.path}-${i}`}>
             <a
               href={row.url ?? '#'}
-              className="cp-result"
-              data-selected={i === 0 ? '' : undefined}
-              role="presentation"
+              className="cp-result cp-result-recent"
               onClick={(e) => {
                 if (!row.url) e.preventDefault();
               }}
@@ -621,12 +939,24 @@ function EmptyState({
       </div>
       {emptyActions.length > 0 && (
         <div className="cp-empty-chips">
-          {emptyActions.map((a) => (
-            <span key={a.label} className="cp-empty-chip">
-              {a.label}
-              {a.kbd && <span className="cp-chip-kbd">{a.kbd}</span>}
-            </span>
-          ))}
+          {emptyActions.map((a) =>
+            a.onSelect ? (
+              <button
+                type="button"
+                key={a.label}
+                className="cp-empty-chip cp-empty-chip-button"
+                onClick={a.onSelect}
+              >
+                {a.label}
+                {a.kbd && <span className="cp-chip-kbd">{a.kbd}</span>}
+              </button>
+            ) : (
+              <span key={a.label} className="cp-empty-chip">
+                {a.label}
+                {a.kbd && <span className="cp-chip-kbd">{a.kbd}</span>}
+              </span>
+            ),
+          )}
         </div>
       )}
       {recentSearches.length > 0 && (
@@ -676,8 +1006,24 @@ function ErrorState({ onRetry }: { onRetry: () => void }) {
 // ─── Styles ───────────────────────────────────────────────────────────────────
 // Source preserved from docs-ai-vault-search verbatim. `:global(...)` wrappers
 // dropped (now plain global CSS, all class names are `cp-*` prefixed).
+//
+// CSS variables consumed: --cf-primary, --cf-bg, --cf-fg, --cf-muted, --cf-card,
+// --font-sans, --font-mono. When @cofoundy/ui's brand-tokens stylesheet is
+// loaded, these resolve from :root. The :where(...) defaults below provide a
+// safe-but-bland baseline for consumers using this component in isolation —
+// zero specificity, so any consumer-defined value overrides cleanly.
 
 const COMMAND_PALETTE_CSS = `
+:where(.cp-overlay, .cp-trigger) {
+  --cf-primary: #14b8a6;
+  --cf-bg: #0a0e1a;
+  --cf-fg: #e2e8f0;
+  --cf-muted: #94a3b8;
+  --cf-card: #1e293b;
+  --font-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+}
+
 .cp-result-snippet mark,
 .cp-result-title mark {
   background: color-mix(in srgb, var(--cf-primary) 22%, transparent);
@@ -822,6 +1168,35 @@ const COMMAND_PALETTE_CSS = `
   opacity: 1;
   font-weight: 400;
 }
+.cp-input-clear {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  flex-shrink: 0;
+  border: 0;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.04);
+  color: var(--cf-muted);
+  cursor: pointer;
+  padding: 0;
+  transition: background 100ms ease, color 100ms ease;
+}
+.cp-input-clear:hover {
+  background: rgba(255, 255, 255, 0.10);
+  color: var(--cf-fg);
+}
+.cp-input-clear:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--cf-primary) 60%, transparent);
+  outline-offset: 1px;
+}
+[data-theme="light"] .cp-input-clear {
+  background: rgba(15, 23, 42, 0.04);
+}
+[data-theme="light"] .cp-input-clear:hover {
+  background: rgba(15, 23, 42, 0.10);
+}
 
 .cp-results-wrap {
   flex: 1;
@@ -829,7 +1204,11 @@ const COMMAND_PALETTE_CSS = `
   overflow-x: hidden;
   min-height: 0;
   scrollbar-width: thin;
+  transition: opacity 80ms ease-out;
 }
+/* Previous results are still on screen but no longer reflect the input —
+   dim them while the debounce timer waits to fire the next fetch. */
+.cp-results-wrap[data-stale] { opacity: 0.55; }
 .cp-results-meta {
   padding: 14px 20px 8px;
   display: flex;
@@ -926,9 +1305,42 @@ const COMMAND_PALETTE_CSS = `
   line-height: 1.35;
   letter-spacing: -0.012em;
   color: color-mix(in srgb, var(--cf-fg) 96%, white);
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 0;
+}
+.cp-result-title-text {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+  min-width: 0;
+}
+.cp-result-role {
+  display: inline-flex;
+  align-items: center;
+  height: 16px;
+  padding: 0 6px;
+  border-radius: 3px;
+  font-family: var(--font-mono);
+  font-weight: 500;
+  font-size: 9.5px;
+  line-height: 1;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: color-mix(in srgb, var(--cf-muted) 25%, var(--cf-fg));
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  flex-shrink: 0;
+}
+[data-theme="light"] .cp-result-role {
+  background: rgba(15, 23, 42, 0.04);
+  border-color: rgba(15, 23, 42, 0.10);
+}
+.cp-result-role[data-role="team"] {
+  color: color-mix(in srgb, var(--cf-primary) 35%, var(--cf-fg));
+  background: color-mix(in srgb, var(--cf-primary) 10%, transparent);
+  border-color: color-mix(in srgb, var(--cf-primary) 22%, transparent);
 }
 .cp-result[data-selected] .cp-result-title { color: #ffffff; }
 [data-theme="light"] .cp-result[data-selected] .cp-result-title { color: var(--cf-fg); }
@@ -950,9 +1362,14 @@ const COMMAND_PALETTE_CSS = `
   line-height: 1.45;
   color: color-mix(in srgb, var(--cf-fg) 68%, transparent);
   margin-top: 3px;
-  white-space: nowrap;
+  /* 2-line clamp keeps the FTS5 <mark> visible even when it lands mid-snippet. */
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
   overflow: hidden;
   text-overflow: ellipsis;
+  word-break: break-word;
 }
 .cp-result[data-selected] .cp-result-snippet {
   color: color-mix(in srgb, var(--cf-fg) 88%, white);
@@ -1125,6 +1542,22 @@ const COMMAND_PALETTE_CSS = `
   50%      { opacity: 0.9; }
 }
 
+/* WCAG 2.3.3 — honor the OS-level motion preference. Replace flourish
+   animations with instant cuts and stop the loading shimmer pulse. */
+@media (prefers-reduced-motion: reduce) {
+  .cp-overlay,
+  .cp-surface,
+  .cp-overlay-sheet .cp-surface,
+  .cp-overlay-auto .cp-surface,
+  .cp-skeleton-title,
+  .cp-skeleton-path,
+  .cp-skeleton-snippet,
+  .cp-results-wrap {
+    animation: none !important;
+    transition: none !important;
+  }
+}
+
 .cp-state {
   padding: 2.25rem 1.25rem;
   text-align: center;
@@ -1230,6 +1663,23 @@ const COMMAND_PALETTE_CSS = `
   background: rgba(0, 0, 0, 0.02);
   border-color: rgba(15, 23, 42, 0.08);
 }
+.cp-empty-chip-button {
+  cursor: pointer;
+  transition: background 100ms ease, border-color 100ms ease, color 100ms ease;
+}
+.cp-empty-chip-button:hover {
+  background: rgba(255, 255, 255, 0.06);
+  border-color: rgba(255, 255, 255, 0.14);
+  color: var(--cf-fg);
+}
+.cp-empty-chip-button:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--cf-primary) 60%, transparent);
+  outline-offset: 2px;
+}
+[data-theme="light"] .cp-empty-chip-button:hover {
+  background: rgba(15, 23, 42, 0.06);
+  border-color: rgba(15, 23, 42, 0.16);
+}
 .cp-chip-kbd {
   display: inline-flex;
   align-items: center;
@@ -1313,8 +1763,11 @@ const COMMAND_PALETTE_CSS = `
   font-size: 13px;
   cursor: pointer;
   transition: background 120ms ease, border-color 120ms ease, color 120ms ease;
-  min-width: 44px;
-  min-height: 44px;
+}
+/* Touch devices need a 44×44 hit target. Apply only on coarse pointers so
+   desktop mouse users keep the 32px-tall pill we visually designed for. */
+@media (pointer: coarse) {
+  .cp-trigger { min-width: 44px; min-height: 44px; padding: 0 12px; }
 }
 .cp-trigger:hover {
   background: rgba(255, 255, 255, 0.06);
diff --git a/src/index.ts b/src/index.ts
index 263737c..24eac1b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -552,6 +552,7 @@ export type {
 export {
   CommandPalette,
   CommandPaletteTrigger,
+  useCommandPaletteHotkeys,
 } from "./components/command-palette/CommandPalette";
 export type {
   CommandPaletteProps,
diff --git a/src/stories/command-palette/CommandPalette.stories.tsx b/src/stories/command-palette/CommandPalette.stories.tsx
index df14285..ec562ad 100644
--- a/src/stories/command-palette/CommandPalette.stories.tsx
+++ b/src/stories/command-palette/CommandPalette.stories.tsx
@@ -100,6 +100,9 @@ const erroringSearch: SearchFn = async () => {
   throw new Error('upstream search index unavailable');
 };
 
+// Stories use a no-op onNavigate so clicking a hit doesn't actually navigate
+// away from the Storybook frame. Wire onSelect to Storybook's actions panel
+// when iterating on telemetry behaviour locally.
 function Harness(props: Parameters<typeof CommandPalette>[0]) {
   const [open, setOpen] = useState(true);
   return (
@@ -107,10 +110,7 @@ function Harness(props: Parameters<typeof CommandPalette>[0]) {
       {...props}
       open={open}
       onOpenChange={setOpen}
-      onNavigate={(url) => {
-        // eslint-disable-next-line no-console
-        console.log('[CommandPalette] navigate →', url);
-      }}
+      onNavigate={() => {}}
     />
   );
 }
