Production tooltips: styled tooltips everywhere, shortcuts surfaced, dev-speak culled

Owner-approved full pass (tooltip wave, 2026-09-25). Mechanism: icon/pill
controls ride the styled Radix tooltip via a new Hint composition
(components/ui/hint.tsx) — the shared primitive adopted as-is, no
restyling; the shortcut appends as an em-dash suffix off the LIVE registry
(a rebind in Settings → Keyboard changes the suffix): "Dictate — ⌘D".
Surface-owned keys (Esc closes, Enter submits) ride a raw binding prop.
Native title= stays only for truncation-reveals (dock spans, the rename
field) and menu-interior abbreviations (MenuShell untouched). One
em-dash pattern; per-state truth on the send square (busy = "Stop the
reply — Esc", idle = "Send — ↵"), Enter on the plan verdict's accept,
"Stop dictation (Esc)" kept verbatim per the owner's flag.

Copy: the dev-speak cull — no pipeline/prober/tier/wave vocabulary
anywhere a user reads. New pins in tests/tooltip-mechanism.test.tsx
(hintText composition, asChild no-wrapper-DOM, the auto-update hint
constant); dock truncation titles pinned native; graph-chrome + settings
pins updated to the new copy.

Live-verified on :3001 — 12.6ms hover appearance (no native 1s lag);
glyphs render on every suffixed surface (⌘D, ⌘K, ⌘⇧F, ⌘,, ⌘B, F2, ↵,
Esc); per-page probes confirm Settings entry, Home logo, session search,
Start session, Close sidebar, model + thinking pills, stats summary,
rename title, plan chip, coverage ring, send square, cost button, node
search (⌘F), graph gear, settings close (Close — Esc), keyboard section
"Fixed — part of this screen", auto-update hint, light-mode "Coming
soon", the three slot rosters, graph-tools hint. Esc still closes the
settings dialog.

tests/render-activity-dock.test.tsx

@@ -204,6 +204,10 @@ describe("activity section render", () => {
 		assert.match(html, /Background agents/);
 		// Total cost: nothing priced → "—" in the header.
 		assert.match(html, /activity-total-cost[^>]*>—</);
+		// Truncation-reveals KEEP native title (tooltip wave mechanism rule):
+		// the truncated activity + title spans carry title= — a styled
+		// tooltip adds nothing over an ellipsis reveal.
+		assert.match(html, /title="building sandbox…"/);
 	});
 
 

tests/render-graph-chrome.test.tsx

@@ -39,7 +39,9 @@ describe("GraphChromeRow — the empty-graph ruling (owner, 2026-09-25)", () =>
 		assert.ok(html.includes('data-testid="import-notes"'));
 		assert.ok(html.includes("Import notes…"));
 		assert.ok(!html.includes("Search nodes…"), "search is a lie on an empty graph");
-		assert.ok(!html.includes('title="Rendering settings"'), "settings is a lie on an empty graph");
+		// the settings gear is the lucide-settings svg (tooltip wave: its old
+		// native title is gone — the styled tooltip carries the label now)
+		assert.ok(!html.includes("lucide-settings"), "settings is a lie on an empty graph");
 		assert.ok(!html.includes("graph-chrome-fade-in"), "nothing gated = nothing fading in");
 	});
 
@@ -47,7 +49,7 @@ describe("GraphChromeRow — the empty-graph ruling (owner, 2026-09-25)", () =>
 		const html = renderToStaticMarkup(createElement(GraphChromeRow, { ...PROPS, isEmpty: false }));
 		assert.ok(html.includes('data-testid="import-notes"'));
 		assert.ok(html.includes("Search nodes…"));
-		assert.ok(html.includes('title="Rendering settings"'));
+		assert.ok(html.includes("lucide-settings"), "the settings gear renders");
 		// the appear-once fade rides exactly the two gated controls, never Import Notes
 		assert.equal(html.split("graph-chrome-fade-in").length - 1, 2, "two fade carriers: search + settings");
 	});

tests/render-plan-block.test.tsx

@@ -140,7 +140,7 @@ describe("plan block render", () => {
 		// Snapshot statuses render as carried.
 		assert.match(html, /data-testid="plan-node-a" data-status="visited"/);
 		assert.match(html, /data-testid="plan-node-b" data-status="upcoming"/);
-		assert.match(html, /Open the full plan/);
+		assert.ok(html.includes('aria-label="Open the full plan"'), "the trigger names itself (tooltip copy)");
 	});
 
 });

tests/render-settings.test.tsx

@@ -69,7 +69,7 @@ describe("AgentSection (thin SSR)", () => {
 			assert.ok(html.includes(`data-testid="slot-model-${slot}"`), `${slot} model trigger`);
 			assert.ok(html.includes(`data-testid="slot-thinking-${slot}"`), `${slot} thinking trigger`);
 			// the roster hint rides every row
-			assert.ok(html.includes("Prober + Teacher") || slot !== "strong", "strong roster");
+			assert.ok(html.includes("The main model for your sessions") || slot !== "strong", "strong roster");
 		}
 		// Fix wave: no Default anywhere — an unpicked slot reads "—"
 		// (the owner's no-factory-fallback language), and no menu
@@ -107,7 +107,7 @@ describe("AgentSection (thin SSR)", () => {
 		const rows = [...toolsGroup.matchAll(/data-testid="(graph-tools-row|tool-row-\w+)"/g)].map((m) => m[1]);
 		assert.equal(rows[0], "graph-tools-row", "graph tools is the FIRST row of the Tools group");
 		// (the apostrophe in "sessions'" HTML-escapes — match up to it)
-		assert.ok(html.includes("Connects prior sessions"), "the describing hint");
+		assert.ok(html.includes("Lets the tutor consult your knowledge map between sessions"), "the describing hint");
 		assert.ok((html.split('data-testid="graph-tools-row"')[1] ?? "").includes('aria-checked="true"'), "absent = on");
 		const rowHtml = html.split('data-testid="graph-tools-row"')[1]?.split('data-testid="tool-row-')[0] ?? "";
 		assert.ok(!rowHtml.includes("opacity-40"), "lit while the graph is on (the search row may dim — no keys in SSR)");
@@ -198,7 +198,7 @@ describe("AppearanceSection (thin SSR)", () => {
 	it("mode is rendered DISABLED — dark-only this wave, no lying control", () => {
 		const html = renderToStaticMarkup(<AppearanceSection appearance={undefined} onSectionChange={() => {}} />);
 		assert.ok(tagOf(html, "select-mode").includes("disabled"), "mode select disabled");
-		assert.ok(html.includes("Light ships with the design wave"));
+		assert.ok(html.includes("Coming soon"));
 		// The whole row dims, graph-view style (the control never adds its own).
 		assert.ok(tagOf(html, "row-mode").includes("opacity-40"), "mode row dims whole");
 	});
@@ -238,7 +238,7 @@ describe("KeyboardSection (thin SSR)", () => {
 
 	it("displayOnly actions list but never offer Rebind", () => {
 		const html = renderToStaticMarkup(<KeyboardSection />);
-		assert.ok(html.includes("Owned by a surface — not rebindable"));
+		assert.ok(html.includes("Fixed — part of this screen"));
 		assert.ok(!html.includes(`data-testid="kbd-rebind-question-next-row"`), "surface keys stay put");
 		assert.ok(!html.includes(`data-testid="kbd-rebind-model-menu-pick"`));
 	});

tests/tooltip-mechanism.test.tsx

@@ -0,0 +1,61 @@
+/**
+ * Tooltip-wave mechanism pins (owner, 2026-09-25): the composition rule —
+ * icon/pill controls ride the styled Radix tooltip via Hint, the shortcut
+ * appended as an em-dash suffix off the LIVE registry (a rebind changes
+ * the suffix); truncation-reveals keep native title=; the copy carries no
+ * internal vocabulary. Node has no navigator → IS_MAC is false → the mod
+ * glyph renders "Ctrl+" here; the composition logic is the pin, not the
+ * platform glyph. (Node 26 ships navigator.platform — on this Mac the real
+ * ⌘/⇧ glyphs render, so they're pinned as-is.)
+ */
+
+import React from "react";
+(globalThis as Record<string, unknown>).React = React;
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { Hint, hintText } from "../components/ui/hint.tsx";
+import { AUTO_UPDATE_HINT } from "../components/settings/settings-dialog.tsx";
+
+describe("hintText — the em-dash composition", () => {
+	it("a registry action appends the LIVE binding (override-aware source)", () => {
+		assert.equal(hintText("Dictate", "toggle-dictation"), "Dictate — ⌘D");
+		assert.equal(hintText("Settings", "open-settings"), "Settings — ⌘,");
+		assert.equal(hintText("Search sessions", "sessions-search"), "Search sessions — ⌘⇧F");
+	});
+
+	it("surface-owned keys ride the binding prop (no registry entry)", () => {
+		assert.equal(hintText("Close", undefined, "escape"), "Close — Esc");
+		assert.equal(hintText("Send", undefined, "enter"), "Send — ↵");
+	});
+
+	it("no shortcut = the label alone, no dangling dash", () => {
+		assert.equal(hintText("Home"), "Home");
+		assert.equal(hintText("Stop dictation (Esc)"), "Stop dictation (Esc)");
+	});
+});
+
+describe("spot-pins: the dev-speak cull (owner copy review at merge)", () => {
+	it("the auto-update hint is honest user language — no stream jargon", () => {
+		assert.equal(AUTO_UPDATE_HINT, "Automatic updates arrive in an upcoming release");
+		assert.ok(!AUTO_UPDATE_HINT.includes("wave"), "no stream vocabulary");
+	});
+});
+
+describe("Hint — the mechanism (SSR: the tooltip itself stays closed)", () => {
+	it("asChild: no wrapper DOM — the control keeps its own testid and classes", () => {
+		const html = renderToStaticMarkup(
+			createElement(Hint, {
+				label: "Dictate",
+				action: "toggle-dictation",
+				children: createElement("button", { "data-testid": "dictation-toggle", className: "the-quiet-chrome" }, "Dictate"),
+			}),
+		);
+		assert.match(html, /^<button/, "the trigger IS the button — nothing wraps it");
+		assert.ok(html.includes('data-testid="dictation-toggle"'));
+		assert.ok(html.includes("the-quiet-chrome"));
+		assert.ok(!html.includes("<span"), "no portal content renders while closed");
+	});
+});