docs(voice): scope prompt hints and translate the new section

Vocabulary hints apply to compatible transcription endpoints; local speech providers ignore them. Keep the new section available at the same anchor in both documentation languages.
fix(dictation): keep transcription context opt-in
2026-11-08 17:34:51 +00:00 · 2026-11-06 03:20:13 +00:00 · 2026-11-06 03:13:21 +00:00
36 changed files with 270 additions and 1266 deletions
@@ -68,7 +68,7 @@ the sidebar. Apply it as `backgroundColor`; setting `opacity` on the control als

 `destructive` is filled with `destructive`. It only appears inside a confirm. The button on the page is `outline`; the destructive button is the confirm button inside the dialog.

-Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. The hit region is not the painted area: a filled toolbar control such as the composer's send or stop keeps the 44pt frame and paints a 36pt disc inside it (`TOOLBAR_DISC_SIZE`), so it does not outweigh its unpainted neighbours. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
+Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.

 One gate, `resolveControlSizing`, picks touch or pointer sizing: touch when the layout is compact or the device has a touch screen. An iPad with the sidebar docked is wide and touch-sized; a desktop is pointer-sized; a phone is both compact and touch. The touch-screen fact is read once at startup (`hasTouchScreen` in `hooks/use-fine-pointer.ts`), so attaching a mouse or keyboard to a tablet never shrinks its controls. Stylesheets take sizes from `bySizing({ touch, pointer })`, which resolves to a breakpoint value, so a caller never sees which sizing it got. Rows, icon buttons and icon slots take theirs from `styles/density.ts`, which uses the same gate. An `{ xs, md }` literal for a hit target or glyph is wrong: on an iPad it yields the pointer size.

@@ -226,8 +226,7 @@ its own.
  inactive. An async action can navigate before its menu closes; a hidden panel must not leave a
  portal backdrop blocking the destination. On web the chat suspends one commit after it goes
  inactive, and that inactive commit is where the surface unmounts.
- Anchoring, flipping, edge clamping, and capping a surface's width to the display live in
-  `components/ui/anchor.ts`, shared with the hover card, and are unit-tested. Clamping moves a
-  surface but cannot shrink it, so the width cap is what keeps a wide menu on a narrow screen. Fix positioning bugs there, not at a call site.
+- Anchoring, flipping, and edge clamping live in `components/ui/anchor.ts`, shared with the hover
+  card, and are unit-tested. Fix positioning bugs there, not at a call site.
 - Everything else about floating surfaces on Android — Portal/Modal escape, lifecycle gates,
  status-bar offset, the open flash — is in [floating-panels.md](floating-panels.md).
@@ -1,127 +0,0 @@
-import { expect, test } from "../support/fixtures";
-import { addProjectFlow } from "../support/helpers/add-project-flow";
-import { gotoAppShell } from "../support/helpers/app";
-import {
-  chooseFooterOverflowAction,
-  expectFooterLine,
-  expectFooterMenusInsideViewport,
-  expectFooterNeverClipped,
-  expectFooterOverflowActions,
-  footerOverflowMenu,
-  openFooterOverflow,
-  seedDockedSidebarWidth,
-  watchFooterClipping,
-} from "../support/helpers/sidebar-footer-overflow";
-import { addOfflineHostsAndReload } from "../support/helpers/hosts";
-import { openCompactSidebar } from "../support/helpers/usage-sidebar-item";
-
-const TOUCH_CONTROL = 44;
-const MIN_SIDEBAR_WIDTH = 200;
-const ALL_INLINE = [
-  "sidebar-add-project",
-  "sidebar-usage-icon",
-  "sidebar-hosts-trigger",
-  "sidebar-help",
-  "sidebar-settings",
-];
-// Five 44pt buttons and the row's padding need 236pt; 200pt holds three and the caret.
-const NARROW_TOUCH_LINE = [
-  "sidebar-add-project",
-  "sidebar-hosts-trigger",
-  "sidebar-footer-overflow",
-  "sidebar-settings",
-];
-
-test.describe("Sidebar footer on a touch screen", () => {
-  test.use({ viewport: { width: 1280, height: 800 }, hasTouch: true });
-
-  test("a narrow docked sidebar moves the actions it can't fit behind a caret", async ({
-    page,
-  }) => {
-    await seedDockedSidebarWidth(page, MIN_SIDEBAR_WIDTH);
-    await watchFooterClipping(page);
-    await gotoAppShell(page);
-    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
-    await expectFooterNeverClipped(page);
-
-    await test.step("Help opens as a page of the overflow menu", async () => {
-      await openFooterOverflow(page);
-      await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
-      await chooseFooterOverflowAction(page, "Help and support");
-      await expect(page.getByRole("menuitem", { name: "What's new" })).toBeVisible();
-      await expect(page.getByTestId("sidebar-help-menu")).toHaveCount(0);
-      await page.keyboard.press("Escape");
-      await expect(footerOverflowMenu(page)).toBeHidden();
-    });
-
-    await test.step("Usage opens from the overflow menu", async () => {
-      await openFooterOverflow(page);
-      await chooseFooterOverflowAction(page, "Usage");
-      await expect(footerOverflowMenu(page)).toBeHidden();
-      await expect(page.getByTestId("usage-modal")).toBeVisible();
-      await page.keyboard.press("Escape");
-      await expect(page.getByTestId("usage-modal")).toBeHidden();
-    });
-
-    await test.step("Add project and Settings shortcuts still work", async () => {
-      await page.keyboard.press("Control+o");
-      await expect(addProjectFlow(page)).toBeVisible();
-      await page.keyboard.press("Escape");
-      await expect(addProjectFlow(page)).toBeHidden();
-      await page.keyboard.press("Control+,");
-      await expect(page).toHaveURL(/\/settings\/general$/);
-    });
-  });
-
-  test("the default sidebar width keeps all five actions inline", async ({ page }) => {
-    await gotoAppShell(page);
-    await expectFooterLine(page, { testIDs: ALL_INLINE, controlSize: TOUCH_CONTROL });
-  });
-});
-
-test.describe("Sidebar footer in a compact overlay narrower than the footer", () => {
-  test.use({ viewport: { width: 220, height: 800 }, hasTouch: true });
-
-  test("the overflow menu reaches the hidden actions", async ({ page }) => {
-    await watchFooterClipping(page);
-    await gotoAppShell(page);
-    await openCompactSidebar(page);
-    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
-    await expectFooterNeverClipped(page);
-    await openFooterOverflow(page);
-    await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
-    await expectFooterMenusInsideViewport(page);
-  });
-});
-
-test.describe("Sidebar footer on a short, narrow phone", () => {
-  // 164pt for buttons holds Settings, Add project and the caret, so Hosts moves behind it.
-  test.use({ viewport: { width: 180, height: 360 }, hasTouch: true });
-
-  test("the overflow Hosts page scrolls to its last host and Add host", async ({ page }) => {
-    await gotoAppShell(page);
-    await addOfflineHostsAndReload(
-      page,
-      Array.from({ length: 10 }, (_, index) => ({
-        serverId: `overflow-host-${index}`,
-        label: `Overflow host ${index}`,
-      })),
-    );
-    await openCompactSidebar(page);
-    await expectFooterLine(page, {
-      testIDs: ["sidebar-add-project", "sidebar-footer-overflow", "sidebar-settings"],
-      controlSize: TOUCH_CONTROL,
-    });
-    await openFooterOverflow(page);
-    await expectFooterOverflowActions(page, ["Usage", "Hosts", "Help and support"]);
-    await expectFooterMenusInsideViewport(page);
-    await chooseFooterOverflowAction(page, "Hosts");
-    await expectFooterMenusInsideViewport(page);
-    const addHost = page.getByRole("menuitem", { name: "Add host" });
-    await addHost.scrollIntoViewIfNeeded();
-    await expect(page.getByRole("menuitem", { name: "Overflow host 9" })).toBeVisible();
-    await expect(addHost).toBeInViewport();
-    await addHost.click();
-    await expect(page.getByText("Add connection", { exact: true })).toBeVisible();
-  });
-});
@@ -8,7 +8,7 @@ import {
  openProjectViaDaemon,
 } from "../support/helpers/new-workspace";
 import { getServerId } from "../support/helpers/server-id";
-import { openCompactSettings, openSettingsHostSection } from "../support/helpers/settings";
+import { openSettingsHostSection } from "../support/helpers/settings";
 import {
  expectFooterItemSetting,
  expectFooterSeparator,
@@ -42,7 +42,6 @@ import {
 import { seedSidebarFooterPreferences } from "../support/helpers/sidebar-nav-settings";
 import { waitForSettledPosition } from "../support/helpers/sheet-layout";
 import { createTempGitRepo } from "../support/helpers/workspace";
-import { buildOpenProjectRoute } from "@/utils/host-routes";

 const WIDE = { width: 1440, height: 900 };
 const COMPACT = { width: 390, height: 844 };
@@ -71,112 +70,7 @@ async function footerClip(page: Page) {
  return (await page.locator('[data-testid="sidebar-footer"]:visible').boundingBox())!;
 }

-async function setPageVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
-  await page.evaluate((state) => {
-    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
-    Object.defineProperty(document, "hidden", {
-      configurable: true,
-      get: () => state === "hidden",
-    });
-    document.dispatchEvent(new Event("visibilitychange"));
-  }, visibility);
-}
-
 test.describe("Usage item", () => {
-  test("visible summary refreshes every five minutes without opening Usage", async ({ page }) => {
-    let usedPct = 31;
-    const usage = await installUsageReportsFixture(page, {
-      lists: [
-        () => [
-          {
-            ...claudeAndCodexReports()[0]!,
-            report: {
-              status: "available",
-              windows: [
-                { id: "five_hour", label: "Session", shortLabel: "5h", summary: true, usedPct },
-              ],
-            },
-          },
-        ],
-      ],
-    });
-    await page.clock.install();
-    await page.setViewportSize(WIDE);
-    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
-    await gotoAppShell(page);
-    await expectPinnedUsage(page, ["31% 5h"]);
-    const startingUrl = page.url();
-    await qaScreenshot(page, "usage-auto-refresh-initial", { kind: "footer" });
-    const requestsBeforeRefresh = usage.listRequests();
-
-    usedPct = 42;
-    await page.clock.fastForward(5 * 60_000);
-    await qaScreenshot(page, "usage-auto-refresh-after-interval", { kind: "footer" });
-    await expectPinnedUsage(page, ["42% 5h"]);
-    await expect(usageModal(page)).toHaveCount(0);
-    await expect(page).toHaveURL(startingUrl);
-    expect(usage.listRequests()).toEqual([
-      ...requestsBeforeRefresh,
-      { forceRefresh: false, reportIds: undefined, agentId: undefined },
-    ]);
-
-    await setPageVisibility(page, "hidden");
-    const requestsBeforeBackgrounding = usage.listRequests();
-    usedPct = 47;
-    await page.clock.fastForward(5 * 60_000);
-    expect(usage.listRequests()).toEqual(requestsBeforeBackgrounding);
-    await expectPinnedUsage(page, ["42% 5h"]);
-    await setPageVisibility(page, "visible");
-    await page.clock.fastForward(5 * 60_000);
-    await expectPinnedUsage(page, ["47% 5h"]);
-    expect(usage.listRequests()).toEqual([
-      ...requestsBeforeBackgrounding,
-      { forceRefresh: false, reportIds: undefined, agentId: undefined },
-    ]);
-
-    await page.setViewportSize(COMPACT);
-    await expect(usageItem(page)).toHaveCount(0);
-    const requestsBeforeHiding = usage.listRequests();
-    await page.clock.fastForward(5 * 60_000);
-    expect(usage.listRequests()).toEqual(requestsBeforeHiding);
-
-    await openCompactSidebar(page);
-    await expectPinnedUsage(page, ["47% 5h"]);
-    await expect(page.getByTestId("agent-list-backdrop")).toBeVisible();
-    usedPct = 53;
-    await page.clock.fastForward(5 * 60_000);
-    await expectPinnedUsage(page, ["53% 5h"]);
-    await expect(usageModal(page)).toHaveCount(0);
-
-    await page.setViewportSize(WIDE);
-    await openSidebarNavSettings(page);
-    await setFooterItemVisible(page, "usage", false);
-    await leaveSettings(page);
-    await expectNoUsageItem(page);
-    const requestsBeforeDisabling = usage.listRequests();
-    await page.clock.fastForward(5 * 60_000);
-    expect(usage.listRequests()).toEqual(requestsBeforeDisabling);
-  });
-
-  test("Usage settings do not poll reports while the sidebar is inactive", async ({ page }) => {
-    const usage = await installUsageReportsFixture(page, {
-      lists: [() => claudeAndCodexReports()],
-    });
-    await page.clock.install();
-    await page.setViewportSize(COMPACT);
-    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
-    await gotoAppShell(page);
-    await openCompactSettings(page, buildOpenProjectRoute());
-    await openSettingsHostSection(page, getServerId(), "usage");
-    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
-    await expect(usageItem(page)).toHaveCount(0);
-    const requestsBeforeWaiting = usage.listRequests();
-
-    await page.clock.fastForward(5 * 60_000);
-    expect(usage.listRequests()).toEqual(requestsBeforeWaiting);
-    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
-  });
-
  test("both compact footer entry points open Usage as a sheet", async ({ page }) => {
    await page.setViewportSize(COMPACT);
    await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });
@@ -22,27 +22,15 @@ export async function addOfflineHostAndReload(
  page: Page,
  input: { serverId: string; label: string; primaryLabel?: string },
 ): Promise<void> {
-  await addOfflineHostsAndReload(page, [input], { primaryLabel: input.primaryLabel });
-}
-
-/** Adds several unreachable hosts with one reload. See `addOfflineHostAndReload`. */
-export async function addOfflineHostsAndReload(
-  page: Page,
-  hosts: Array<{ serverId: string; label: string }>,
-  options: { primaryLabel?: string } = {},
-): Promise<void> {
-  const nowIso = new Date().toISOString();
-  const offlineHosts = hosts.map((host) =>
-    buildSeededHost({
-      serverId: host.serverId,
-      label: host.label,
-      endpoint: "127.0.0.1:59999",
-      nowIso,
-    }),
-  );
+  const offlineHost = buildSeededHost({
+    serverId: input.serverId,
+    label: input.label,
+    endpoint: "127.0.0.1:59999",
+    nowIso: new Date().toISOString(),
+  });

  await page.evaluate(
-    ({ hosts: added, keys, primaryLabel }) => {
+    ({ host, keys, primaryLabel }) => {
      const nonce = localStorage.getItem(keys.nonce);
      if (!nonce) {
        throw new Error("Expected the e2e seed nonce before overriding the host registry.");
@@ -52,22 +40,20 @@ export async function addOfflineHostsAndReload(
      if (primaryLabel && registry[0]) {
        registry[0].label = primaryLabel;
      }
-      for (const host of added) {
-        if (!registry.some((entry) => entry.serverId === host.serverId)) {
-          registry.push(host);
-        }
+      if (!registry.some((entry) => entry.serverId === host.serverId)) {
+        registry.push(host);
      }
      localStorage.setItem(keys.registry, JSON.stringify(registry));
      localStorage.setItem(keys.disableSeedOnce, nonce);
    },
    {
-      hosts: offlineHosts,
+      host: offlineHost,
      keys: {
        registry: REGISTRY_KEY,
        nonce: SEED_NONCE_KEY,
        disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
      },
-      primaryLabel: options.primaryLabel,
+      primaryLabel: input.primaryLabel,
    },
  );

@@ -1,127 +0,0 @@
-import { expect, type Locator, type Page } from "@playwright/test";
-
-/** Every footer control that can sit in the icon line, caret included. */
-const FOOTER_LINE_TEST_IDS = [
-  "sidebar-add-project",
-  "sidebar-usage-icon",
-  "sidebar-hosts-trigger",
-  "sidebar-help",
-  "sidebar-footer-overflow",
-  "sidebar-settings",
-];
-
-// Browser layout boxes include floating-point rounding, even for whole-pixel styles.
-const GEOMETRY_TOLERANCE = 0.01;
-
-/** Open the app with the docked sidebar at `width`, as if the user had dragged it there. */
-export async function seedDockedSidebarWidth(page: Page, width: number): Promise<void> {
-  await page.addInitScript((sidebarWidth) => {
-    localStorage.setItem("panel-state", JSON.stringify({ version: 17, state: { sidebarWidth } }));
-  }, width);
-}
-
-/**
- * From the first frame, record any frame in which a footer button reaches past its row, so a row
- * laid out before it measured shows up even if it lasted one frame.
- */
-export async function watchFooterClipping(page: Page): Promise<void> {
-  await page.addInitScript((testIDs) => {
-    const clippedFrames: string[] = [];
-    Object.assign(window, { __footerClippedFrames: clippedFrames });
-    const sample = () => {
-      for (const row of document.querySelectorAll('[data-testid="sidebar-footer-bottom-line"]')) {
-        const rowRect = row.getBoundingClientRect();
-        if (rowRect.width === 0) continue;
-        for (const testID of testIDs) {
-          const button = row.querySelector(`[data-testid="${testID}"]`);
-          if (button && button.getBoundingClientRect().right > rowRect.right + 0.5) {
-            clippedFrames.push(testID);
-          }
-        }
-      }
-      requestAnimationFrame(sample);
-    };
-    requestAnimationFrame(sample);
-  }, FOOTER_LINE_TEST_IDS);
-}
-
-export async function expectFooterNeverClipped(page: Page): Promise<void> {
-  const clipped = await page.evaluate(
-    () => (window as unknown as { __footerClippedFrames: string[] }).__footerClippedFrames,
-  );
-  expect(clipped).toEqual([]);
-}
-
-function footerLine(page: Page): Locator {
-  return page.locator('[data-testid="sidebar-footer-bottom-line"]:visible');
-}
-
-export function footerOverflowMenu(page: Page): Locator {
-  return page.getByTestId("sidebar-footer-overflow-menu");
-}
-
-/**
- * The icon line shows exactly `testIDs`, in order, each `controlSize` square and wholly inside the
- * line's box, so no button is cut off by the sidebar's edge.
- */
-export async function expectFooterLine(
-  page: Page,
-  input: { testIDs: string[]; controlSize: number },
-): Promise<void> {
-  const line = footerLine(page);
-  await expect(line).toHaveCount(1);
-  await expect
-    .poll(async () =>
-      line
-        .locator(FOOTER_LINE_TEST_IDS.map((testID) => `[data-testid="${testID}"]`).join(","))
-        .evaluateAll((elements) => elements.map((element) => element.getAttribute("data-testid"))),
-    )
-    .toEqual(input.testIDs);
-  const { row, buttons } = await line.evaluate((element, testIDs) => {
-    const rect = (node: Element) => {
-      const { x, width, height } = node.getBoundingClientRect();
-      return { x, width, height };
-    };
-    return {
-      row: rect(element),
-      buttons: testIDs.map((testID) => rect(element.querySelector(`[data-testid="${testID}"]`)!)),
-    };
-  }, input.testIDs);
-  for (const button of buttons) {
-    expect(Math.abs(button.width - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
-    expect(Math.abs(button.height - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
-    expect(button.x).toBeGreaterThanOrEqual(row.x - GEOMETRY_TOLERANCE);
-    expect(button.x + button.width).toBeLessThanOrEqual(row.x + row.width + GEOMETRY_TOLERANCE);
-  }
-}
-
-export async function openFooterOverflow(page: Page): Promise<void> {
-  await footerLine(page).getByTestId("sidebar-footer-overflow").click();
-  await expect(footerOverflowMenu(page)).toBeVisible();
-}
-
-/** The overflow menu lists exactly these actions, in row order. */
-export async function expectFooterOverflowActions(page: Page, names: string[]): Promise<void> {
-  await expect(footerOverflowMenu(page).getByRole("menuitem")).toHaveText(names);
-}
-
-export async function chooseFooterOverflowAction(page: Page, name: string): Promise<void> {
-  await footerOverflowMenu(page).getByRole("menuitem", { name }).click();
-}
-
-/** Every row of the open overflow menu, and of the page it opened, is inside the viewport's width. */
-export async function expectFooterMenusInsideViewport(page: Page): Promise<void> {
-  const viewport = page.viewportSize()!;
-  const rows = page.getByRole("menuitem");
-  await expect(rows.first()).toBeVisible();
-  const boxes = await rows.evaluateAll((elements) =>
-    elements.map((element) => {
-      const { x, width } = element.getBoundingClientRect();
-      return { x, width };
-    }),
-  );
-  for (const box of boxes) {
-    expect(box.x).toBeGreaterThanOrEqual(0);
-    expect(box.x + box.width).toBeLessThanOrEqual(viewport.width);
-  }
-}
@@ -17,7 +17,6 @@ import {
  Text,
  useWindowDimensions,
  View,
-  type LayoutChangeEvent,
 } from "react-native";
 import { Gesture, ScrollView as GHScrollView } from "react-native-gesture-handler";
 import Animated, { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
@@ -41,17 +40,6 @@ import { SidebarSeparator } from "@/components/sidebar/sidebar-separator";
 import { SidebarNavRows } from "@/components/sidebar/sidebar-nav-rows";
 import { SidebarFooterIconHighlight } from "@/components/sidebar/sidebar-footer-icon-highlight";
 import { SidebarHelpMenu } from "@/components/sidebar/sidebar-help-menu";
-import { SidebarFooterOverflowMenu } from "@/components/sidebar/sidebar-footer-overflow-menu";
-import {
-  resolveSidebarFooterLayout,
-  SIDEBAR_FOOTER_ACTIONS,
-  type SidebarFooterAction,
-} from "@/components/sidebar-footer-layout";
-import {
-  controlSizingForLayout,
-  mapLayout,
-  TOOLBAR_CONTROL_SIZES,
-} from "@/components/ui/control-geometry";
 import { SidebarResizeHandle } from "@/components/sidebar-resize-handle";
 import { DensityIcon } from "@/components/ui/density-icon";
 import { SidebarSectionHeader } from "@/components/sidebar/sidebar-section-header";
@@ -67,7 +55,6 @@ import {
  type SidebarWorkspaceEntry,
 } from "@/hooks/use-sidebar-workspaces-list";
 import { density } from "@/styles/density";
-import { SPACING } from "@/styles/theme";
 import { useSidebarModel } from "@/components/sidebar/sidebar-model";
 import type { PinnedSidebarGroups } from "@/hooks/use-sidebar-pins";
 import { RetainedPanelActivity } from "@/components/retained-panel";
@@ -92,9 +79,6 @@ import { SidebarWorkspaceList } from "./sidebar-workspace-list";

 type SidebarTheme = ReturnType<typeof useUnistyles>["theme"];

-/** The footer icon line's inset; the overflow layout counts it as space the buttons can't use. */
-const FOOTER_ROW_PADDING = SPACING[2];
-
 const DEV_BUILD_LABEL = process.env.EXPO_PUBLIC_PASEO_DEV_BUILD_LABEL?.trim() || null;

 interface SidebarSharedProps {
@@ -426,72 +410,35 @@ function SidebarFooter({
 }) {
  const newAgentKeys = useShortcutKeys("new-agent");
  const settingsKeys = useShortcutKeys("toggle-settings");
-  const isCompactLayout = useIsCompactFormFactor();
-  const [rowWidth, setRowWidth] = useState(0);
-  const handleRowLayout = useCallback((event: LayoutChangeEvent) => {
-    setRowWidth(event.nativeEvent.layout.width);
-  }, []);
-  const { inline, overflow } = useMemo(
-    () =>
-      resolveSidebarFooterLayout({
-        rowWidth,
-        controlSize: TOOLBAR_CONTROL_SIZES[controlSizingForLayout(isCompactLayout)],
-        rowPadding: FOOTER_ROW_PADDING,
-        actions: SIDEBAR_FOOTER_ACTIONS,
-      }),
-    [rowWidth, isCompactLayout],
-  );
-  const isInline = (action: SidebarFooterAction) => inline.includes(action);

-  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end. Actions that
-  // don't fit move behind a caret before Settings.
+  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end.
  return (
    <UsageSidebarRoot>
      <View style={styles.footerContainer} testID="sidebar-footer">
        <SidebarFooterRows onBeforeNavigate={onBeforeNavigate} />
-        <View
-          style={styles.sidebarFooter}
-          onLayout={handleRowLayout}
-          testID="sidebar-footer-bottom-line"
-        >
-          {isInline("add-project") ? (
-            <FooterIconButton
-              onPress={handleOpenProject}
-              testID="sidebar-add-project"
-              label={labels.addProject}
-              icon={FolderPlus}
-              shortcutKeys={newAgentKeys}
-            />
-          ) : null}
-          {isInline("usage") ? <SidebarUsageIcon label={labels.usage} /> : null}
-          {isInline("hosts") ? (
-            <SidebarHostPicker
-              label={labels.hosts}
-              onAddHost={handleAddHost}
-              onOpenHostSettings={handleOpenHostSettings}
-            />
-          ) : null}
+        <View style={styles.sidebarFooter} testID="sidebar-footer-bottom-line">
+          <FooterIconButton
+            onPress={handleOpenProject}
+            testID="sidebar-add-project"
+            label={labels.addProject}
+            icon={FolderPlus}
+            shortcutKeys={newAgentKeys}
+          />
+          <SidebarUsageIcon label={labels.usage} />
+          <SidebarHostPicker
+            label={labels.hosts}
+            onAddHost={handleAddHost}
+            onOpenHostSettings={handleOpenHostSettings}
+          />
          <View style={styles.footerSpacer} />
-          {isInline("help") ? <SidebarHelpMenu /> : null}
-          {overflow.length > 0 ? (
-            <SidebarFooterOverflowMenu
-              actions={overflow}
-              labels={labels}
-              onAddProject={handleOpenProject}
-              onSettings={handleSettings}
-              onAddHost={handleAddHost}
-              onOpenHostSettings={handleOpenHostSettings}
-            />
-          ) : null}
-          {isInline("settings") ? (
-            <FooterIconButton
-              onPress={handleSettings}
-              testID="sidebar-settings"
-              label={labels.settings}
-              icon={Settings}
-              shortcutKeys={settingsKeys}
-            />
-          ) : null}
+          <SidebarHelpMenu />
+          <FooterIconButton
+            onPress={handleSettings}
+            testID="sidebar-settings"
+            label={labels.settings}
+            icon={Settings}
+            shortcutKeys={settingsKeys}
+          />
        </View>
      </View>
    </UsageSidebarRoot>
@@ -990,12 +937,10 @@ const styles = StyleSheet.create((theme) => ({
    borderTopColor: theme.colors.border,
  },
  // Buttons sit edge to edge; their own inset spaces the glyphs.
-  // As tall as its buttons from the first frame, which places none until the row has measured.
  sidebarFooter: {
    flexDirection: "row",
    alignItems: "center",
-    minHeight: mapLayout(density.iconButton, (height) => height + theme.spacing[1.5] * 2),
-    paddingHorizontal: FOOTER_ROW_PADDING,
+    paddingHorizontal: theme.spacing[2],
    paddingVertical: theme.spacing[1.5],
  },
  // Pushes Help and Settings to the end of the icon line.
@@ -1,89 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  resolveSidebarFooterLayout,
-  SIDEBAR_FOOTER_ACTIONS,
-} from "@/components/sidebar-footer-layout";
-import { DEFAULT_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
-
-const TOUCH = 44;
-const POINTER = 28;
-const ROW_PADDING = 8;
-
-function layout(rowWidth: number, controlSize: number) {
-  return resolveSidebarFooterLayout({
-    rowWidth,
-    controlSize,
-    rowPadding: ROW_PADDING,
-    actions: SIDEBAR_FOOTER_ACTIONS,
-  });
-}
-
-describe("sidebar footer layout", () => {
-  it("keeps every action inline at the default width with either sizing", () => {
-    for (const controlSize of [TOUCH, POINTER]) {
-      expect(layout(DEFAULT_SIDEBAR_WIDTH, controlSize)).toEqual({
-        inline: ["add-project", "usage", "hosts", "help", "settings"],
-        overflow: [],
-      });
-    }
-  });
-
-  it("keeps every action inline at the minimum width with pointer sizing", () => {
-    expect(layout(MIN_SIDEBAR_WIDTH, POINTER).overflow).toEqual([]);
-  });
-
-  // The iPhone Duo report: the folded sidebar column is about the minimum width, and touch
-  // sizing makes five 44pt buttons plus padding 236pt wide.
-  it("moves Help and Usage behind the caret at the minimum width with touch sizing", () => {
-    expect(layout(MIN_SIDEBAR_WIDTH, TOUCH)).toEqual({
-      inline: ["add-project", "hosts", "settings"],
-      overflow: ["usage", "help"],
-    });
-  });
-
-  it("keeps Settings and Add project inline longest", () => {
-    // Three slots: two actions and the caret.
-    expect(layout(3 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
-      inline: ["add-project", "settings"],
-      overflow: ["usage", "hosts", "help"],
-    });
-    // Two slots: Settings and the caret.
-    expect(layout(2 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
-      inline: ["settings"],
-      overflow: ["add-project", "usage", "hosts", "help"],
-    });
-  });
-
-  it("puts everything behind the caret when only the caret fits", () => {
-    expect(layout(TOUCH + 2 * ROW_PADDING - 10, TOUCH)).toEqual({
-      inline: [],
-      overflow: ["add-project", "usage", "hosts", "help", "settings"],
-    });
-  });
-
-  it("fits all five actions exactly at their combined width", () => {
-    const exact = 5 * TOUCH + 2 * ROW_PADDING;
-    expect(layout(exact, TOUCH).overflow).toEqual([]);
-    // Browser layout rounds a little below the exact width.
-    expect(layout(exact - 0.4, TOUCH).overflow).toEqual([]);
-    expect(layout(exact - 1, TOUCH).overflow).toEqual(["usage", "help"]);
-  });
-
-  it("only places the actions it is given", () => {
-    expect(
-      resolveSidebarFooterLayout({
-        rowWidth: 3 * TOUCH + 2 * ROW_PADDING,
-        controlSize: TOUCH,
-        rowPadding: ROW_PADDING,
-        actions: ["add-project", "hosts", "settings"],
-      }),
-    ).toEqual({ inline: ["add-project", "hosts", "settings"], overflow: [] });
-  });
-
-  // Laying out against a guessed width would paint a clipped row for a frame on narrow sidebars.
-  it("places nothing before the row has been measured", () => {
-    for (const controlSize of [TOUCH, POINTER]) {
-      expect(layout(0, controlSize)).toEqual({ inline: [], overflow: [] });
-    }
-  });
-});
@@ -1,62 +0,0 @@
-/** The sidebar footer's icon line, in row order. */
-export const SIDEBAR_FOOTER_ACTIONS = [
-  "add-project",
-  "usage",
-  "hosts",
-  "help",
-  "settings",
-] as const;
-
-export type SidebarFooterAction = (typeof SIDEBAR_FOOTER_ACTIONS)[number];
-
-/** The order actions keep their place in a row too narrow for all of them. */
-const KEEP_ORDER: readonly SidebarFooterAction[] = [
-  "settings",
-  "add-project",
-  "hosts",
-  "usage",
-  "help",
-];
-
-/** Measured widths land a hair under the exact sum of their parts. */
-const MEASUREMENT_TOLERANCE = 0.5;
-
-export interface SidebarFooterLayout {
-  /** Actions drawn in the row, in row order. */
-  inline: SidebarFooterAction[];
-  /** Actions behind the overflow caret, in row order. Empty when everything fits. */
-  overflow: SidebarFooterAction[];
-}
-
-/**
- * Splits the footer's actions between the row and the overflow menu. Buttons keep their full size;
- * when they don't all fit, the caret takes one slot and the actions that lose their place move
- * behind it, Help first and Settings last. Nothing is placed until the row has a measured width.
- */
-export function resolveSidebarFooterLayout(input: {
-  rowWidth: number;
-  controlSize: number;
-  rowPadding: number;
-  actions: readonly SidebarFooterAction[];
-}): SidebarFooterLayout {
-  const { rowWidth, controlSize, rowPadding, actions } = input;
-  // An unmeasured row stays empty: any guess would paint a clipped row for a frame on a narrow
-  // sidebar before the real width arrives.
-  if (rowWidth <= 0) {
-    return { inline: [], overflow: [] };
-  }
-  const slots = Math.floor(
-    (rowWidth - rowPadding * 2 + MEASUREMENT_TOLERANCE) / Math.max(controlSize, 1),
-  );
-  if (slots >= actions.length) {
-    return { inline: [...actions], overflow: [] };
-  }
-  const inlineCount = Math.max(slots - 1, 0);
-  const kept = new Set(
-    KEEP_ORDER.filter((action) => actions.includes(action)).slice(0, inlineCount),
-  );
-  return {
-    inline: actions.filter((action) => kept.has(action)),
-    overflow: actions.filter((action) => !kept.has(action)),
-  };
-}
@@ -1,69 +0,0 @@
-import type { ReactElement } from "react";
-import { Text, View } from "react-native";
-import type { LucideIcon } from "lucide-react-native";
-import { StyleSheet } from "react-native-unistyles";
-import { DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
-import { DensityIcon } from "@/components/ui/density-icon";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
-import { density } from "@/styles/density";
-import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
-
-/**
- * A footer icon that opens a menu. Sized and drawn like the footer's other icon buttons; the
- * tooltip stays out of the way while the menu is open.
- */
-export function SidebarFooterMenuTrigger({
-  icon,
-  label,
-  menuOpen,
-  testID,
-}: {
-  icon: LucideIcon;
-  label: string;
-  menuOpen: boolean;
-  testID: string;
-}): ReactElement {
-  return (
-    <Tooltip delayDuration={300} enabledOnDesktop={!menuOpen}>
-      <TooltipTrigger asChild>
-        <View>
-          <DropdownMenuTrigger
-            style={styles.trigger}
-            testID={testID}
-            accessibilityRole="button"
-            accessibilityLabel={label}
-          >
-            {({ hovered, pressed, open }) => (
-              <>
-                <SidebarFooterIconHighlight visible={pressed || open} />
-                <DensityIcon
-                  icon={icon}
-                  size="md"
-                  color={hovered ? "foreground" : "foregroundMuted"}
-                />
-              </>
-            )}
-          </DropdownMenuTrigger>
-        </View>
-      </TooltipTrigger>
-      <TooltipContent side="top" align="center" offset={8}>
-        <Text style={styles.tooltipText}>{label}</Text>
-      </TooltipContent>
-    </Tooltip>
-  );
-}
-
-const styles = StyleSheet.create((theme) => ({
-  trigger: {
-    width: density.iconButton,
-    height: density.iconButton,
-    alignItems: "center",
-    justifyContent: "center",
-    paddingVertical: theme.spacing[1],
-    paddingHorizontal: theme.spacing[1],
-  },
-  tooltipText: {
-    fontSize: theme.fontSize.base,
-    color: theme.colors.popoverForeground,
-  },
-}));
@@ -1,245 +0,0 @@
-import { useCallback, useMemo, useState, type ReactElement } from "react";
-import { useTranslation } from "react-i18next";
-import {
-  ChevronUp,
-  CircleGauge,
-  CircleHelp,
-  FolderPlus,
-  Plus,
-  Server,
-  Settings,
-} from "lucide-react-native";
-import { withUnistyles } from "react-native-unistyles";
-import { HostStatusDotSlot } from "@/components/hosts/host-picker";
-import type { SidebarFooterAction } from "@/components/sidebar-footer-layout";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuSubTrigger,
-  type MenuPageDefinition,
-} from "@/components/ui/dropdown-menu";
-import { Shortcut } from "@/components/ui/shortcut";
-import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
-import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
-import { useHosts } from "@/runtime/host-runtime";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
-import { orderHostsLocalFirst } from "@/types/host-connection";
-import { useOpenSidebarUsage } from "@/usage";
-import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
-import { SidebarHelpMenuItems } from "./sidebar-help-menu";
-
-const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
-const ThemedFolderPlus = withUnistyles(FolderPlus);
-const ThemedCircleGauge = withUnistyles(CircleGauge);
-const ThemedServer = withUnistyles(Server);
-const ThemedCircleHelp = withUnistyles(CircleHelp);
-const ThemedSettings = withUnistyles(Settings);
-const ThemedPlus = withUnistyles(Plus);
-const addProjectLeading = <ThemedFolderPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-const usageLeading = <ThemedCircleGauge size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-const hostsLeading = <ThemedServer size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-const helpLeading = <ThemedCircleHelp size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-const settingsLeading = <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-const addHostLeading = <ThemedPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
-
-const HOSTS_PAGE_ID = "hosts";
-const HELP_PAGE_ID = "help";
-
-export interface SidebarFooterOverflowMenuProps {
-  /** The footer actions that did not fit in the row, in row order. */
-  actions: readonly SidebarFooterAction[];
-  labels: { addProject: string; hosts: string; settings: string; usage: string };
-  onAddProject: () => void;
-  onSettings: () => void;
-  onAddHost: () => void;
-  onOpenHostSettings: (serverId: string) => void;
-}
-
-/**
- * The caret at the end of a footer row too narrow for every action. It lists the actions that
- * lost their place, with the same test IDs they carry in the row; Hosts and Help, menus of their
- * own in the row, open as pages of this menu.
- */
-export function SidebarFooterOverflowMenu({
-  actions,
-  labels,
-  onAddProject,
-  onSettings,
-  onAddHost,
-  onOpenHostSettings,
-}: SidebarFooterOverflowMenuProps): ReactElement {
-  const { t } = useTranslation();
-  const [open, setOpen] = useState(false);
-  const openUsage = useOpenSidebarUsage();
-  const newAgentKeys = useShortcutKeys("new-agent");
-  const settingsKeys = useShortcutKeys("toggle-settings");
-  const helpLabel = t("sidebar.help.trigger");
-  const addProjectTrailing = useMemo(
-    () => (newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null),
-    [newAgentKeys],
-  );
-  const settingsTrailing = useMemo(
-    () => (settingsKeys ? <Shortcut chord={settingsKeys} /> : null),
-    [settingsKeys],
-  );
-
-  const pages = useMemo((): MenuPageDefinition[] => {
-    const result: MenuPageDefinition[] = [];
-    if (actions.includes("hosts")) {
-      result.push({
-        id: HOSTS_PAGE_ID,
-        title: labels.hosts,
-        content: <HostsPage onAddHost={onAddHost} onOpenHostSettings={onOpenHostSettings} />,
-      });
-    }
-    if (actions.includes("help")) {
-      result.push({ id: HELP_PAGE_ID, title: helpLabel, content: <SidebarHelpMenuItems /> });
-    }
-    return result;
-  }, [actions, helpLabel, labels.hosts, onAddHost, onOpenHostSettings]);
-
-  function renderAction(action: SidebarFooterAction): ReactElement {
-    switch (action) {
-      case "add-project":
-        return (
-          <DropdownMenuItem
-            key={action}
-            testID="sidebar-add-project"
-            leading={addProjectLeading}
-            trailing={addProjectTrailing}
-            onSelect={onAddProject}
-          >
-            {labels.addProject}
-          </DropdownMenuItem>
-        );
-      case "usage":
-        return (
-          <DropdownMenuItem
-            key={action}
-            testID="sidebar-usage-icon"
-            leading={usageLeading}
-            onSelect={openUsage}
-          >
-            {labels.usage}
-          </DropdownMenuItem>
-        );
-      case "hosts":
-        return (
-          <DropdownMenuSubTrigger
-            key={action}
-            id={HOSTS_PAGE_ID}
-            testID="sidebar-hosts-trigger"
-            leading={hostsLeading}
-          >
-            {labels.hosts}
-          </DropdownMenuSubTrigger>
-        );
-      case "help":
-        return (
-          <DropdownMenuSubTrigger
-            key={action}
-            id={HELP_PAGE_ID}
-            testID="sidebar-help"
-            leading={helpLeading}
-          >
-            {helpLabel}
-          </DropdownMenuSubTrigger>
-        );
-      case "settings":
-        return (
-          <DropdownMenuItem
-            key={action}
-            testID="sidebar-settings"
-            leading={settingsLeading}
-            trailing={settingsTrailing}
-            onSelect={onSettings}
-          >
-            {labels.settings}
-          </DropdownMenuItem>
-        );
-    }
-  }
-
-  return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <SidebarFooterMenuTrigger
-        icon={ChevronUp}
-        label={t("sidebar.actions.moreActions")}
-        menuOpen={open}
-        testID="sidebar-footer-overflow"
-      />
-      <DropdownMenuContent
-        side="top"
-        align="end"
-        offset={8}
-        width={240}
-        pages={pages}
-        scrollable
-        testID="sidebar-footer-overflow-menu"
-      >
-        {actions.map(renderAction)}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  );
-}
-
-/** The host picker's choices as a menu page: each host opens its settings, then Add host. */
-function HostsPage({
-  onAddHost,
-  onOpenHostSettings,
-}: {
-  onAddHost: () => void;
-  onOpenHostSettings: (serverId: string) => void;
-}): ReactElement {
-  const { t } = useTranslation();
-  const hosts = useHosts();
-  const localServerId = useLocalDaemonServerId();
-  const orderedHosts = useMemo(
-    () => orderHostsLocalFirst(hosts, localServerId),
-    [hosts, localServerId],
-  );
-
-  return (
-    <>
-      {orderedHosts.map((host) => (
-        <HostRow
-          key={host.serverId}
-          serverId={host.serverId}
-          label={host.label}
-          onOpenHostSettings={onOpenHostSettings}
-        />
-      ))}
-      {orderedHosts.length > 0 ? <DropdownMenuSeparator /> : null}
-      <DropdownMenuItem testID="sidebar-host-add" leading={addHostLeading} onSelect={onAddHost}>
-        {t("settings.addHost")}
-      </DropdownMenuItem>
-    </>
-  );
-}
-
-function HostRow({
-  serverId,
-  label,
-  onOpenHostSettings,
-}: {
-  serverId: string;
-  label: string;
-  onOpenHostSettings: (serverId: string) => void;
-}): ReactElement {
-  const handleSelect = useCallback(
-    () => onOpenHostSettings(serverId),
-    [onOpenHostSettings, serverId],
-  );
-  const leading = useMemo(() => <HostStatusDotSlot serverId={serverId} />, [serverId]);
-  return (
-    <DropdownMenuItem
-      testID={`sidebar-host-row-${serverId}`}
-      leading={leading}
-      onSelect={handleSelect}
-    >
-      {label}
-    </DropdownMenuItem>
-  );
-}
@@ -1,5 +1,5 @@
 import { useCallback, useState } from "react";
-import { View } from "react-native";
+import { Text, View } from "react-native";
 import { Activity, CircleHelp, Gift, Keyboard } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
@@ -12,13 +12,17 @@ import {
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
+  DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
+import { DensityIcon } from "@/components/ui/density-icon";
+import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { useAppDiagnosticStore } from "@/diagnostics/store";
 import { useHardwareKeyboardPresent } from "@/keyboard";
 import { useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { useSessionStore } from "@/stores/session-store";
+import { density } from "@/styles/density";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import type { HostProfile } from "@/types/host-connection";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -73,32 +77,12 @@ function HostVersionHint({ host }: { host: HostProfile }) {
  );
 }

-/** The Help menu's trigger, and the menu it opens. */
 export function SidebarHelpMenu() {
-  const { t } = useTranslation();
-  const [open, setOpen] = useState(false);
-
-  return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <SidebarFooterMenuTrigger
-        icon={CircleHelp}
-        label={t("sidebar.help.trigger")}
-        menuOpen={open}
-        testID="sidebar-help"
-      />
-      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
-        <SidebarHelpMenuItems />
-      </DropdownMenuContent>
-    </DropdownMenu>
-  );
-}
-
-/** The Help menu's rows, shared by the Help menu and the footer's overflow page for it. */
-export function SidebarHelpMenuItems() {
  const { t } = useTranslation();
  const shortcutsAvailable = useHardwareKeyboardPresent();
  const openAppDiagnostic = useAppDiagnosticStore((state) => state.open);
  const setShortcutsDialogOpen = useKeyboardShortcutsStore((state) => state.setShortcutsDialogOpen);
+  const [open, setOpen] = useState(false);
  const version = formatVersionWithPrefix(resolveAppVersion());
  const hosts = useHosts();

@@ -115,65 +99,105 @@ export function SidebarHelpMenuItems() {
  }, []);

  return (
-    <>
-      <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
-      {shortcutsAvailable ? (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <Tooltip delayDuration={300} enabledOnDesktop={!open}>
+        <TooltipTrigger asChild>
+          <View>
+            <DropdownMenuTrigger
+              style={styles.trigger}
+              testID="sidebar-help"
+              accessibilityRole="button"
+              accessibilityLabel={t("sidebar.help.trigger")}
+            >
+              {({ hovered, pressed, open: menuOpen }) => (
+                <>
+                  <SidebarFooterIconHighlight visible={pressed || menuOpen} />
+                  <DensityIcon
+                    icon={CircleHelp}
+                    size="md"
+                    color={hovered ? "foreground" : "foregroundMuted"}
+                  />
+                </>
+              )}
+            </DropdownMenuTrigger>
+          </View>
+        </TooltipTrigger>
+        <TooltipContent side="top" align="center" offset={8}>
+          <Text style={styles.tooltipText}>{t("sidebar.help.trigger")}</Text>
+        </TooltipContent>
+      </Tooltip>
+      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
+        <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
+        {shortcutsAvailable ? (
+          <DropdownMenuItem
+            testID="sidebar-help-shortcuts"
+            leading={shortcutsLeadingIcon}
+            onSelect={openKeyboardShortcuts}
+          >
+            {t("sidebar.help.shortcuts")}
+          </DropdownMenuItem>
+        ) : null}
        <DropdownMenuItem
-          testID="sidebar-help-shortcuts"
-          leading={shortcutsLeadingIcon}
-          onSelect={openKeyboardShortcuts}
+          testID="sidebar-help-changelog"
+          leading={changelogLeadingIcon}
+          onSelect={openChangelog}
        >
-          {t("sidebar.help.shortcuts")}
+          {t("sidebar.help.whatsNew")}
        </DropdownMenuItem>
-      ) : null}
-      <DropdownMenuItem
-        testID="sidebar-help-changelog"
-        leading={changelogLeadingIcon}
-        onSelect={openChangelog}
-      >
-        {t("sidebar.help.whatsNew")}
-      </DropdownMenuItem>
-      <DropdownMenuItem
-        testID="sidebar-help-diagnostics"
-        leading={diagnosticLeadingIcon}
-        onSelect={openAppDiagnostic}
-      >
-        {t("sidebar.help.diagnostics")}
-      </DropdownMenuItem>
-      <DropdownMenuSeparator />
-      <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
-      <DropdownMenuItem
-        testID="sidebar-help-discord"
-        leading={discordLeadingIcon}
-        onSelect={openDiscord}
-      >
-        {t("sidebar.help.discord")}
-      </DropdownMenuItem>
-      <DropdownMenuItem
-        testID="sidebar-help-github"
-        leading={githubLeadingIcon}
-        onSelect={openGitHubIssue}
-      >
-        {t("sidebar.help.github")}
-      </DropdownMenuItem>
-      <DropdownMenuSeparator />
-      <View style={styles.versionList}>
-        <DropdownMenuHint
-          style={styles.versionHint}
-          trailing={version}
-          testID="sidebar-help-version"
+        <DropdownMenuItem
+          testID="sidebar-help-diagnostics"
+          leading={diagnosticLeadingIcon}
+          onSelect={openAppDiagnostic}
        >
-          {t("sidebar.help.appName")}
-        </DropdownMenuHint>
-        {hosts.map((host) => (
-          <HostVersionHint key={host.serverId} host={host} />
-        ))}
-      </View>
-    </>
+          {t("sidebar.help.diagnostics")}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
+        <DropdownMenuItem
+          testID="sidebar-help-discord"
+          leading={discordLeadingIcon}
+          onSelect={openDiscord}
+        >
+          {t("sidebar.help.discord")}
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          testID="sidebar-help-github"
+          leading={githubLeadingIcon}
+          onSelect={openGitHubIssue}
+        >
+          {t("sidebar.help.github")}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <View style={styles.versionList}>
+          <DropdownMenuHint
+            style={styles.versionHint}
+            trailing={version}
+            testID="sidebar-help-version"
+          >
+            {t("sidebar.help.appName")}
+          </DropdownMenuHint>
+          {hosts.map((host) => (
+            <HostVersionHint key={host.serverId} host={host} />
+          ))}
+        </View>
+      </DropdownMenuContent>
+    </DropdownMenu>
  );
 }

 const styles = StyleSheet.create((theme) => ({
+  trigger: {
+    width: density.iconButton,
+    height: density.iconButton,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: theme.spacing[1],
+    paddingHorizontal: theme.spacing[1],
+  },
+  tooltipText: {
+    fontSize: theme.fontSize.base,
+    color: theme.colors.popoverForeground,
+  },
  versionList: {
    gap: theme.spacing[1],
    paddingVertical: theme.spacing[2],
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, fitSurfaceWidth, getTransformOrigin, type Rect } from "./anchor";
+import { computePosition, getTransformOrigin, type Rect } from "./anchor";

 const DISPLAY: Rect = { x: 0, y: 0, width: 1000, height: 800 };
 const TRIGGER: Rect = { x: 100, y: 100, width: 40, height: 20 };
@@ -97,26 +97,3 @@ describe("getTransformOrigin", () => {
    expect(getTransformOrigin(placement, alignment)).toEqual(expected);
  });
 });
-
-describe("fitSurfaceWidth", () => {
-  it("leaves a surface that fits the display alone, capped at the display", () => {
-    expect(fitSurfaceWidth({ width: 240, minWidth: 180 }, 1000)).toEqual({
-      width: 240,
-      minWidth: 180,
-      maxWidth: 984,
-    });
-  });
-
-  it("shrinks a surface wider than a narrow display to the space inside its edge padding", () => {
-    expect(fitSurfaceWidth({ width: 240, minWidth: 180, maxWidth: 320 }, 220)).toEqual({
-      width: 204,
-      minWidth: 180,
-      maxWidth: 204,
-    });
-    expect(fitSurfaceWidth({ minWidth: 180 }, 150)).toEqual({
-      width: undefined,
-      minWidth: 134,
-      maxWidth: 134,
-    });
-  });
-});
@@ -120,27 +120,6 @@ function clampToDisplayArea(input: {
  };
 }

-export interface SurfaceWidth {
-  width?: number;
-  minWidth?: number;
-  maxWidth?: number;
-}
-
-/**
- * Caps a surface's requested width to the display. Position clamping can move a surface but not
- * shrink it, so a menu wider than a narrow screen would otherwise hang off the far edge.
- */
-export function fitSurfaceWidth(requested: SurfaceWidth, displayWidth: number): SurfaceWidth {
-  const available = Math.max(displayWidth - EDGE_PADDING * 2, 0);
-  const cap = (value: number | undefined) =>
-    typeof value === "number" ? Math.min(value, available) : undefined;
-  return {
-    width: cap(requested.width),
-    minWidth: cap(requested.minWidth),
-    maxWidth: cap(requested.maxWidth) ?? available,
-  };
-}
-
 export function computePosition({
  triggerRect,
  contentSize,
@@ -14,8 +14,6 @@ import {
  getControlInteractionPhase,
  TOOLBAR_CONTROL_HEIGHT,
  TOOLBAR_CONTROL_SIZES,
-  TOOLBAR_DISC_SIZE,
-  TOOLBAR_DISC_SIZES,
  TOUCH_TARGET,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
@@ -92,11 +90,6 @@ describe("control sizing gate", () => {
    // Composer toolbar controls: a full target on touch, unchanged 28 on pointer.
    expect(TOOLBAR_CONTROL_SIZES).toEqual({ touch: TOUCH_TARGET, pointer: 28 });
    expect(TOOLBAR_CONTROL_HEIGHT).toEqual({ xs: TOUCH_TARGET, md: 28 });
-    // A filled toolbar control paints a 36pt disc inside its 44pt touch frame, and fills its
-    // 28pt pointer frame exactly, so desktop is unchanged. Its glyph is the `md` glyph.
-    expect(TOOLBAR_DISC_SIZES).toEqual({ touch: 36, pointer: TOOLBAR_CONTROL_SIZES.pointer });
-    expect(TOOLBAR_DISC_SIZE).toEqual({ xs: 36, md: 28 });
-    expect(iconSizeFor("md")).toEqual({ touch: 20, pointer: 16 });
    for (const size of ["sm", "md"] as const) {
      expect(controlHeightForLayout(size, true)).toBeGreaterThan(
        controlHeightForLayout(size, false),
@@ -93,14 +93,6 @@ export const ICON_BUTTON_SIZES = {
 export const TOOLBAR_CONTROL_SIZES = { touch: TOUCH_TARGET, pointer: 28 } satisfies SizingValue;
 export const TOOLBAR_CONTROL_HEIGHT = bySizing(TOOLBAR_CONTROL_SIZES);

-/**
- * The painted disc of a filled toolbar control, such as the composer's send and stop. The
- * control keeps the full toolbar hit frame and paints this smaller disc centered inside it, so
- * touch-sized it does not outweigh its unpainted neighbours. Pointer-sized it fills the frame.
- */
-export const TOOLBAR_DISC_SIZES = { touch: 36, pointer: 28 } satisfies SizingValue;
-export const TOOLBAR_DISC_SIZE = bySizing(TOOLBAR_DISC_SIZES);
-
 /**
 * Glyph sizes. Pointer glyphs sit beside 13-14pt text; touch glyphs sit beside iOS's 17pt body
 * text, so each step is larger.
@@ -29,7 +29,6 @@ import type { KeyboardFocusScope } from "@/keyboard/actions";
 import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import {
  computePosition,
-  fitSurfaceWidth,
  getTransformOrigin,
  measureElement,
  type Alignment,
@@ -284,7 +283,11 @@ export function AnchoredSurface({
    const { width: screenWidth } = Dimensions.get("window");
    const resolvedWidthStyle: ViewStyle = fullWidth
      ? { width: screenWidth - horizontalPadding * 2 }
-      : fitSurfaceWidth({ width, minWidth, maxWidth }, screenWidth);
+      : {
+          ...(typeof width === "number" ? { width } : null),
+          ...(typeof minWidth === "number" ? { minWidth } : null),
+          ...(typeof maxWidth === "number" ? { maxWidth } : null),
+        };
    return [
      resolvedWidthStyle,
      {
@@ -35,7 +35,6 @@ import {
  controlSizingForLayout,
  iconSizeFor,
  TOOLBAR_CONTROL_HEIGHT,
-  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { usePanelStore } from "@/stores/panel-store";
 import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
@@ -1118,7 +1117,7 @@ function ComposerCancelButton({
        accessibilityRole="button"
        style={cancelButtonStyle}
      >
-        <View style={styles.cancelButtonDisc}>{icon}</View>
+        {icon}
      </TooltipTrigger>
      <TooltipContent side="top" align="center" offset={8}>
        <View style={styles.tooltipRow}>
@@ -2596,21 +2595,14 @@ const styles = StyleSheet.create((theme: Theme) => ({
    width: "100%",
    gap: theme.spacing[3],
  },
-  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
  cancelButton: {
    width: TOOLBAR_CONTROL_HEIGHT,
    height: TOOLBAR_CONTROL_HEIGHT,
-    alignItems: "center",
-    justifyContent: "center",
-    marginLeft: theme.spacing[1],
-  },
-  cancelButtonDisc: {
-    width: TOOLBAR_DISC_SIZE,
-    height: TOOLBAR_DISC_SIZE,
    borderRadius: theme.borderRadius.full,
    backgroundColor: theme.colors.palette.red[600],
    alignItems: "center",
    justifyContent: "center",
+    marginLeft: theme.spacing[1],
  },
  rightControls: {
    flexDirection: "row",
@@ -33,7 +33,6 @@ import {
  controlSizingForLayout,
  iconSizeFor,
  TOOLBAR_CONTROL_HEIGHT,
-  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
@@ -350,11 +349,7 @@ function VoiceButtonIcon({
  buttonIconSize: number;
 }) {
  if (isDictating) {
-    return (
-      <View style={styles.voiceButtonRecordingDisc}>
-        <Square size={buttonIconSize} color="white" fill="white" />
-      </View>
-    );
+    return <Square size={buttonIconSize} color="white" fill="white" />;
  }
  const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
  if (isMutedRealtime) {
@@ -842,14 +837,12 @@ function SendButtonTooltip({
        testID={submitButtonTestID}
        style={sendButtonCombinedStyle}
      >
-        <View style={submitLabel ? styles.sendButtonDiscLabeled : styles.sendButtonDisc}>
-          <SendButtonContent
-            isSubmitLoading={isSubmitLoading}
-            submitIcon={submitIcon}
-            submitLabel={submitLabel}
-            buttonIconSize={buttonIconSize}
-          />
-        </View>
+        <SendButtonContent
+          isSubmitLoading={isSubmitLoading}
+          submitIcon={submitIcon}
+          submitLabel={submitLabel}
+          buttonIconSize={buttonIconSize}
+        />
      </TooltipTrigger>
      <TooltipContent side="top" align="center" offset={8}>
        <SendTooltipBody label={sendTooltipLabel} sendKeys={sendKeys} />
@@ -1932,6 +1925,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
        styles.voiceButton,
        Boolean(hovered) && !isDictating && styles.iconButtonHovered,
        !isDictationStartEnabled && styles.buttonDisabled,
+        isDictating && styles.voiceButtonRecording,
      ],
      [isDictating, isDictationStartEnabled],
    );
@@ -1980,8 +1974,12 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
      allowEmpty: allowEmptySubmit,
    });
    const sendButtonCombinedStyle = useMemo(
-      () => [styles.sendButton, isPresentedSendDisabled && styles.buttonDisabled],
-      [isPresentedSendDisabled],
+      () => [
+        styles.sendButton,
+        submitLabel ? styles.sendButtonLabeled : undefined,
+        isPresentedSendDisabled && styles.buttonDisabled,
+      ],
+      [isPresentedSendDisabled, submitLabel],
    );
    const overlayContainerStyle = useMemo(
      () => [styles.overlayContainer, { opacity: surfacePresentation.overlay.opacity }],
@@ -2418,38 +2416,23 @@ const styles = StyleSheet.create((theme: Theme) => ({
    alignItems: "center",
    justifyContent: "center",
  },
-  voiceButtonRecordingDisc: {
-    width: TOOLBAR_DISC_SIZE,
-    height: TOOLBAR_DISC_SIZE,
-    borderRadius: theme.borderRadius.full,
+  voiceButtonRecording: {
    backgroundColor: theme.colors.destructive,
-    alignItems: "center",
-    justifyContent: "center",
  },
-  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
  sendButton: {
-    minWidth: TOOLBAR_CONTROL_HEIGHT,
+    width: TOOLBAR_CONTROL_HEIGHT,
    height: TOOLBAR_CONTROL_HEIGHT,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
    alignItems: "center",
    justifyContent: "center",
    marginLeft: theme.spacing[1],
  },
-  sendButtonDisc: {
-    width: TOOLBAR_DISC_SIZE,
-    height: TOOLBAR_DISC_SIZE,
-    borderRadius: theme.borderRadius.full,
-    backgroundColor: theme.colors.accent,
-    alignItems: "center",
-    justifyContent: "center",
-  },
-  sendButtonDiscLabeled: {
-    minWidth: TOOLBAR_DISC_SIZE,
-    height: TOOLBAR_DISC_SIZE,
+  sendButtonLabeled: {
+    width: "auto",
+    minWidth: TOOLBAR_CONTROL_HEIGHT,
    paddingHorizontal: theme.spacing[3],
    borderRadius: theme.borderRadius.full,
-    backgroundColor: theme.colors.accent,
-    alignItems: "center",
-    justifyContent: "center",
  },
  sendButtonLabel: {
    fontSize: theme.fontSize.base,
@@ -1236,7 +1236,6 @@ export const ar: TranslationResources = {
      hosts: "المضيفون",
      settings: "إعدادات",
      closeSidebar: "إغلاق الشريط الجانبي",
-      moreActions: "المزيد من الإجراءات",
    },
    footer: {
      usage: "الاستخدام",
@@ -1244,7 +1244,6 @@ export const en = {
      hosts: "Hosts",
      settings: "Settings",
      closeSidebar: "Close sidebar",
-      moreActions: "More actions",
    },
    footer: {
      usage: "Usage",
@@ -1272,7 +1272,6 @@ export const es: TranslationResources = {
      hosts: "Hosts",
      settings: "Ajustes",
      closeSidebar: "Cerrar barra lateral",
-      moreActions: "Más acciones",
    },
    footer: {
      usage: "Uso",
@@ -1266,7 +1266,6 @@ export const fr: TranslationResources = {
      hosts: "Hôtes",
      settings: "Paramètres",
      closeSidebar: "Fermer la barre latérale",
-      moreActions: "Plus d’actions",
    },
    footer: {
      usage: "Utilisation",
@@ -1250,7 +1250,6 @@ export const ja: TranslationResources = {
      hosts: "ホスト",
      settings: "設定",
      closeSidebar: "サイドバーを閉じる",
-      moreActions: "その他のアクション",
    },
    footer: {
      usage: "使用状況",
@@ -1243,7 +1243,6 @@ export const ko: TranslationResources = {
      hosts: "호스트",
      settings: "설정",
      closeSidebar: "사이드바 닫기",
-      moreActions: "추가 작업",
    },
    footer: {
      usage: "사용량",
@@ -1262,7 +1262,6 @@ export const ptBR: TranslationResources = {
      hosts: "Hosts",
      settings: "Configurações",
      closeSidebar: "Fechar barra lateral",
-      moreActions: "Mais ações",
    },
    footer: {
      usage: "Uso",
@@ -1254,7 +1254,6 @@ export const ru: TranslationResources = {
      hosts: "Хосты",
      settings: "Настройки",
      closeSidebar: "Закрыть боковую панель",
-      moreActions: "Дополнительные действия",
    },
    footer: {
      usage: "Использование",
@@ -1228,7 +1228,6 @@ export const zhCN: TranslationResources = {
      hosts: "Hosts",
      settings: "设置",
      closeSidebar: "关闭侧边栏",
-      moreActions: "更多操作",
    },
    footer: {
      usage: "使用情况",
@@ -33,10 +33,9 @@ import {
 } from "./model";
 import type { UsageReportEntry, UsageView } from "./types";

-// The daemon caches each report for five minutes, so re-reading it is cheap.
-// An explicit refresh passes `forceRefresh` to bypass that cache.
+// The daemon caches each report for five minutes, so re-reading it is cheap. Only
+// an explicit refresh passes `forceRefresh` and reaches the source's API.
 const REPORTS_STALE_TIME_MS = 60_000;
-const REPORTS_REFETCH_INTERVAL_MS = 5 * 60_000;

 /** Every report list of a host: its own and each agent's. */
 function hostUsageQueryKey(serverId: string) {
@@ -165,16 +164,11 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =

 const NO_REPORTS: UsageReportEntry[] = [];

-interface UsageHostReportsInput {
-  serverId: string | null;
-  shouldPoll?: boolean;
-}
-
-/** A host's reports, with periodic refresh enabled only by the visible sidebar summary. */
-export function useUsageHostReports({
-  serverId,
-  shouldPoll = false,
-}: UsageHostReportsInput): UsageReportEntry[] {
+/**
+ * The reports of the sidebar's usage host, which is connected and reports usage; none until they
+ * load, or without a host.
+ */
+export function useUsageHostReports(serverId: string | null): UsageReportEntry[] {
  const setting = useUsageSetting(serverId);
  const queryClient = useQueryClient();
  const query = useFetchQuery({
@@ -183,7 +177,6 @@ export function useUsageHostReports({
    queryFn: serverId ? () => listReports(queryClient, serverId) : skipToken,
    dataShape: "list",
    staleTimeMs: REPORTS_STALE_TIME_MS,
-    refetchInterval: shouldPoll ? REPORTS_REFETCH_INTERVAL_MS : false,
  });
  return setting.enabled ? (query.data ?? NO_REPORTS) : NO_REPORTS;
 }
@@ -16,8 +16,6 @@ import {
  type PressableStateCallbackType,
 } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { useRetainedPanelActive } from "@/components/retained-panel";
-import { useAppVisible } from "@/hooks/use-app-visible";
 import { builtinSidebarNavLabelKey } from "@/sidebar-nav/model";
 import { useUsageDisplay } from "./display";
 import { useUsageInSidebar } from "./in-sidebar";
@@ -38,14 +36,9 @@ import { UsageModal } from "./usage-modal";
 /** Each summary window with data on the usage host, under its source; empty while none has. */
 export function useUsageSummary(): readonly PinnedUsageSource[] {
  const { t } = useTranslation();
-  const active = useRetainedPanelActive();
-  const isAppVisible = useAppVisible();
  const { inSidebar } = useUsageInSidebar();
  const serverId = useUsageHostId();
-  const reports = useUsageHostReports({
-    serverId: inSidebar ? serverId : null,
-    shouldPoll: active && inSidebar && isAppVisible,
-  });
+  const reports = useUsageHostReports(inSidebar ? serverId : null);
  const { preferences } = useUsageDisplay(reports);
  return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }
@@ -33,9 +33,9 @@ async function main(): Promise<void> {

  const apiKey = requireEnv("OPENAI_API_KEY");
  const transcriptionModel = process.env.STT_MODEL ?? "gpt-4o-transcribe";
-  const prompt =
-    process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT ??
-    "Transcribe only what the speaker says. Do not add words. Preserve punctuation and casing. If the audio is silence or non-speech noise, return an empty transcript.";
+  // Mirrors the daemon: no built-in prompt, only an explicit override. Whisper
+  // treats `prompt` as preceding transcript, so a default would bias the baseline.
+  const prompt = process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT?.trim() || undefined;

  const openai = new OpenAI({ apiKey });

@@ -43,7 +43,7 @@ async function main(): Promise<void> {
    file: await import("node:fs").then((fs) => fs.createReadStream(audioPath)),
    language: "en",
    model: transcriptionModel,
-    prompt,
+    ...(prompt ? { prompt } : {}),
    response_format: "json",
    // Aim for determinism.
    temperature: 0,
@@ -57,11 +57,13 @@ class FakeRealtimeSession extends EventEmitter implements StreamingTranscription
 class FakeSttProvider implements SpeechToTextProvider {
  public readonly id = "fake";
  public lastLanguage?: string;
+  public lastPrompt?: string;
  constructor(private readonly session: FakeRealtimeSession) {}
  createSession(
    params: Parameters<SpeechToTextProvider["createSession"]>[0],
  ): StreamingTranscriptionSession {
    this.lastLanguage = params.language;
+    this.lastPrompt = params.prompt;
    return this.session;
  }
 }
@@ -594,3 +596,58 @@ it("closes every dictation stream when one provider cleanup fails", async () =>
  expect(second.closed).toBe(true);
  expect(manager.hasDemand).toBe(false);
 });
+
+describe("DictationStreamManager (transcription prompt)", () => {
+  const originalPromptEnv = process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT;
+
+  afterEach(() => {
+    if (originalPromptEnv === undefined) {
+      delete process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT;
+    } else {
+      process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT = originalPromptEnv;
+    }
+  });
+
+  const startDictation = async (
+    options: { language?: string } = {},
+  ): Promise<{ provider: FakeSttProvider; manager: DictationStreamManager }> => {
+    const session = new FakeRealtimeSession();
+    const provider = new FakeSttProvider(session);
+    const manager = new DictationStreamManager({
+      logger: pino({ level: "silent" }),
+      emit: () => {},
+      sessionId: "prompt",
+      stt: provider,
+      ...(options.language ? { language: options.language } : {}),
+    });
+    await manager.handleStart("d1", "audio/pcm;rate=24000;bits=16");
+    manager.cleanupAll();
+    return { provider, manager };
+  };
+
+  it("sends no prompt by default", async () => {
+    delete process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT;
+    const { provider } = await startDictation();
+    expect(provider.lastPrompt).toBeUndefined();
+  });
+
+  it("sends no prompt for non-English dictation by default", async () => {
+    delete process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT;
+    const { provider } = await startDictation({ language: "zh" });
+    expect(provider.lastLanguage).toBe("zh");
+    expect(provider.lastPrompt).toBeUndefined();
+  });
+
+  it("passes an explicit prompt override through", async () => {
+    process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT =
+      "  Vocabulary: Paseo, Dokploy, Kubernetes.  ";
+    const { provider } = await startDictation();
+    expect(provider.lastPrompt).toBe("Vocabulary: Paseo, Dokploy, Kubernetes.");
+  });
+
+  it.each(["", "   "])("treats a blank override (%j) as no prompt", async (value) => {
+    process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT = value;
+    const { provider } = await startDictation();
+    expect(provider.lastPrompt).toBeUndefined();
+  });
+});
@@ -38,6 +38,12 @@ function parseNonNegativeNumber(value: string | undefined): number | null {
  return parsed;
 }

+/** Unset, empty, and whitespace-only overrides all mean "send no prompt". */
+function readTranscriptionPromptOverride(env: NodeJS.ProcessEnv): string | undefined {
+  const value = env.PASEO_DICTATION_TRANSCRIPTION_PROMPT?.trim();
+  return value ? value : undefined;
+}
+
 function convertPCMToWavBuffer(
  pcmBuffer: Buffer,
  sampleRate: number,
@@ -185,16 +191,16 @@ export class DictationStreamManager {
      return;
    }

-    const transcriptionPrompt =
-      process.env.PASEO_DICTATION_TRANSCRIPTION_PROMPT ??
-      "Transcribe only what the speaker says. Do not add words. Preserve punctuation and casing. If the audio is silence or non-speech noise, return an empty transcript.";
+    // Whisper uses the prompt as transcript context, not silence instructions.
+    // Keep context opt-in so it does not bias speech or introduce unspoken text.
+    const transcriptionPrompt = readTranscriptionPromptOverride(process.env);

    let stt: ReturnType<SpeechToTextProvider["createSession"]>;
    try {
      stt = sttProvider.createSession({
        logger: this.logger.child({ dictationId }),
        language: this.language,
-        prompt: transcriptionPrompt,
+        ...(transcriptionPrompt ? { prompt: transcriptionPrompt } : {}),
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
@@ -1,10 +1,8 @@
-import { execFile, execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
 import { expect, onTestFinished, test } from "vitest";

 import { DaemonClient } from "./test-utils/index.js";
@@ -15,7 +13,7 @@ import {
  DaemonClient as SocketDaemonClient,
  type WebSocketLike,
 } from "@getpaseo/client/internal/daemon-client";
-import { createTestPaseoDaemon, type TestPaseoDaemon } from "./test-utils/paseo-daemon.js";
+import { createTestPaseoDaemon } from "./test-utils/paseo-daemon.js";

 // The reshaped workspace.create.request forwards its worktree `source`
 // (action/refName/branchName/githubPrNumber/worktreeSlug) into createWorktreeCore.
@@ -931,107 +929,3 @@ test("agent creation rejects legacy worktree intent without provisioning or exec
    await rm(tempRoot, { recursive: true, force: true });
  }
 });
-
-test("archiving a local import preserves the containing worktree owned by another daemon", async () => {
-  const artifacts = path.resolve(".artifacts");
-  mkdirSync(artifacts, { recursive: true });
-  const root = mkdtempSync(path.join(artifacts, "local-import-archive-"));
-  const daemons: TestPaseoDaemon[] = [];
-  const clients: DaemonClient[] = [];
-  try {
-    const repo = path.join(root, "repo");
-    const git = (...args: string[]) => execFileSync("git", args, { cwd: repo, stdio: "pipe" });
-    mkdirSync(repo);
-    git("init", "-b", "main");
-    git("config", "user.name", "Paseo Test");
-    git("config", "user.email", "test@getpaseo.local");
-    mkdirSync(path.join(repo, "fixtures"));
-    writeFileSync(path.join(repo, "fixtures", "inside.txt"), "inside\n");
-    writeFileSync(path.join(repo, "outside.txt"), "outside\n");
-    git("add", ".");
-    git("-c", "commit.gpgsign=false", "commit", "-m", "fixture");
-    for (const name of ["owner", "importer"]) {
-      const daemon = await createTestPaseoDaemon({
-        paseoHomeRoot: path.join(root, name),
-        staticDir: path.join(root, name, "static"),
-        agentClients: {},
-      });
-      daemons.push(daemon);
-      const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
-      clients.push(client);
-      await client.connect();
-    }
-    const importer = daemons[1]!;
-    const created = await clients[0]!.createWorkspace({
-      source: {
-        kind: "worktree",
-        cwd: repo,
-        branchName: "feature/local-import",
-        baseBranch: "main",
-      },
-    });
-    expect(created.error).toBeNull();
-    if (!created.workspace) throw new Error("Missing owner workspace");
-    const worktree = created.workspace.workspaceDirectory;
-    const nested = path.join(worktree, "fixtures");
-    writeFileSync(path.join(worktree, "untracked.txt"), "keep me\n");
-    const cli = async (...args: string[]) => {
-      const result = await promisify(execFile)(
-        process.execPath,
-        [
-          "--conditions=source",
-          "--import",
-          import.meta.resolve("tsx"),
-          fileURLToPath(new URL("../../../cli/src/index.ts", import.meta.url)),
-          "--host",
-          `127.0.0.1:${importer.port}`,
-          ...args,
-          "--json",
-        ],
-        {
-          cwd: repo,
-          env: {
-            ...Object.fromEntries(
-              Object.entries(process.env).filter(([key]) => !key.startsWith("PASEO_")),
-            ),
-            PASEO_HOME: importer.paseoHome,
-          },
-          timeout: 30000,
-        },
-      );
-      return JSON.parse(result.stdout);
-    };
-    const imported = await cli("workspace", "create", "--isolation", "local", "--path", nested);
-    console.log("local import", {
-      isolation: imported.isolation,
-      nestedCwd: imported.cwd === nested,
-    });
-    const workspaceId = imported.workspaceId;
-    expect(typeof workspaceId).toBe("string");
-    const archived = await cli("workspace", "archive", workspaceId);
-    console.log("archive", {
-      status: archived.status,
-      parentSurvives: existsSync(worktree),
-      trackedFileSurvives: existsSync(path.join(worktree, "outside.txt")),
-      untrackedFileSurvives: existsSync(path.join(worktree, "untracked.txt")),
-      gitMetadataSurvives: existsSync(path.join(worktree, ".git")),
-    });
-    expect((await clients[0]!.fetchWorkspaces()).entries.map((entry) => entry.id)).toContain(
-      created.workspace.id,
-    );
-    expect(archived.status).toBe("archived");
-    expect(existsSync(worktree), "local import archive must preserve its parent worktree").toBe(
-      true,
-    );
-    expect(readFileSync(path.join(worktree, "outside.txt"), "utf8")).toBe("outside\n");
-    expect(readFileSync(path.join(worktree, "untracked.txt"), "utf8")).toBe("keep me\n");
-    expect(readFileSync(path.join(nested, "inside.txt"), "utf8")).toBe("inside\n");
-    expect((await clients[1]!.fetchWorkspaces()).entries.map((entry) => entry.id)).not.toContain(
-      workspaceId,
-    );
-  } finally {
-    for (const client of clients) await client.close();
-    for (const daemon of daemons.toReversed()) await daemon.close();
-    await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
-  }
-}, 180000);
@@ -142,8 +142,19 @@ Keys and base URLs follow the fallback rule above.
 - `PASEO_VOICE_LOCAL_STT_MODEL`, `PASEO_VOICE_LOCAL_TTS_MODEL`, local voice STT/TTS model IDs
 - `PASEO_DICTATION_LANGUAGE`, dictation STT language
 - `PASEO_VOICE_LANGUAGE`, voice mode STT language; falls back to `PASEO_DICTATION_LANGUAGE` when unset
+- `PASEO_DICTATION_TRANSCRIPTION_PROMPT`, optional OpenAI dictation transcription prompt (including compatible servers). Unset by default; empty or whitespace-only is treated as unset
 - `PASEO_VOICE_LOCAL_TTS_SPEAKER_ID`, `PASEO_VOICE_LOCAL_TTS_SPEED`, optional local voice TTS tuning

+## Transcription Prompt
+
+With the OpenAI provider, including compatible servers, Paseo sends no transcription prompt by default. Whisper-family models use `prompt` as transcript context, so instruction text can distort the transcript or bias its language. Omitting it does not prevent every hallucination on silence or noise.
+
+For OpenAI dictation, set `PASEO_DICTATION_TRANSCRIPTION_PROMPT` to send a prompt explicitly, for example to bias toward project vocabulary. An empty or whitespace-only value means no prompt. Local providers ignore this setting, and voice mode never sends a prompt.
+
+```bash
+PASEO_DICTATION_TRANSCRIPTION_PROMPT="Vocabulary: Paseo, TypeScript."
+```
+
 ## Operational Notes

 Voice mode can launch and control agents. Treat voice prompts with the same care as direct agent instructions, especially when specifying working directories or destructive operations.
@@ -120,8 +120,19 @@ Paseo 在配置的 OpenAI base URL 下使用以下路径：
 - `PASEO_VOICE_LOCAL_STT_MODEL`、`PASEO_VOICE_LOCAL_TTS_MODEL`：本地语音 STT/TTS 模型 ID
 - `PASEO_DICTATION_LANGUAGE`：口述 STT 语言（仅限 OpenAI STT；本地 Parakeet 会忽略）
 - `PASEO_VOICE_LANGUAGE`：语音模式 STT 语言；未设置时退回到 `PASEO_DICTATION_LANGUAGE`（仅限 OpenAI STT；本地 Parakeet 会忽略）
+- `PASEO_DICTATION_TRANSCRIPTION_PROMPT`：可选的 OpenAI 口述转录提示词（包括兼容服务器）。默认不设置；空值或仅含空白字符的值视为未设置
 - `PASEO_VOICE_LOCAL_TTS_SPEAKER_ID`、`PASEO_VOICE_LOCAL_TTS_SPEED`：可选的本地语音 TTS 调优

+## 转录提示词 {#transcription-prompt}
+
+使用 OpenAI Provider（包括兼容服务器）进行口述时，Paseo 默认不发送转录提示词。Whisper 系列模型把 `prompt` 当作转录上下文，因此指令文本可能使转录失真或影响输出语言。不发送提示词也无法消除静音或噪声中的所有幻觉。
+
+对于 OpenAI 口述，可以设置 `PASEO_DICTATION_TRANSCRIPTION_PROMPT` 来显式发送提示词，例如提示项目术语。空值或仅含空白字符的值表示不发送提示词。本地 Provider 会忽略此设置，语音模式也不会发送提示词。
+
+```bash
+PASEO_DICTATION_TRANSCRIPTION_PROMPT="Vocabulary: Paseo, TypeScript."
+```
+
 ## 使用须知 {#operational-notes}

 语音模式可以启动和控制 Agent。请像对待直接的 Agent 指令一样谨慎对待语音提示词，尤其是在指定工作目录或执行破坏性操作时。