Keys section (auth/provider-keys wave): BYOK keys in the settings dialog

Owner-approved design (2026-09-20): a Keys section right after General,
two groups over the merged auth API (GET /api/keys masked statuses,
PUT/DELETE /api/keys/:id, immediate effect, shape-gated 400s):

- Model providers: OpenRouter pinned as an always-visible row (the
  app's lifeline — synthesized when absent so first boot shows it),
  stored provider keys render as they appear, and an Add-provider
  dropdown lists every pi-ai provider that takes an API key. The
  dropdown reads GET /api/keys' optional providers array — the
  Platform interlude (master-routed) derives it from pi-ai's own
  env-key table; until it lands the group shows a pending note
  (rolePins pattern — absent field, no drift, no guessed routes).
- Tools & services: the curated rows — Deepgram (dictation) and the
  Google pair (search key + CSE ID) — with description hints and docs
  links (external links route through the Electron shell to the real
  browser).
- Rows: always-visible paste inputs (owner choice; no reveal —
  plaintext never returns from the store), masked status line
  (…tail · chars · environment|saved), the shadowedByEnv explanation
  when a real env var owns the name, per-row inline 400 messages, Save
  on Enter/button, Delete when present (env-owned keys honestly keep
  their env status after a file delete).
- Unknown auth.json vars surface as read-only dimmed rows — preserved
  by the store, not editable through the curated surface.

classifyKeys/keyStatusLine pure exports drive the two-group
projection; tests: SSR loading state, first-boot synthesis, provider
row classification, addable filtering, unknown-var read-only status
line formatting. Nav grows to six sections (Keys second).

Live-verified: nav order, structure, bad-paste 400s inline, save
round-trip with env-shadow explanation, delete round-trip, env-owned
OpenRouter status stability. Gates: typecheck, lint, 748/748, build.

tests/render-settings.test.tsx

@@ -14,6 +14,7 @@ import { describe, it } from "node:test";
 import { renderToStaticMarkup } from "react-dom/server";
 import { TOGGLE_TOOLS, AgentSection } from "../components/settings/agent-section.tsx";
 import { AppearanceSection, GraphSection } from "../components/settings/appearance-section.tsx";
+import { KeysSection } from "../components/settings/keys-section.tsx";
 import { KeyboardSection } from "../components/settings/keyboard-section.tsx";
 import { SettingsDialogBody, SettingsDialogProvider } from "../components/settings/settings-dialog.tsx";
 import { KEYBOARD_ACTIONS } from "../src/core/index.ts";
@@ -39,12 +40,12 @@ describe("SettingsDialog (the designed surface, SSR)", () => {
 		assert.ok(!html.includes("settings-dialog"));
 	});
 
-	it("the dialog frame: role=dialog + the ✕ + the five-section nav, General active", () => {
+	it("the dialog frame: role=dialog + the ✕ + the six-section nav, General active", () => {
 		const html = renderToStaticMarkup(<SettingsDialogBody onClose={() => {}} />);
 		assert.ok(html.includes('role="dialog"'));
 		assert.ok(html.includes('aria-modal="true"'));
 		assert.ok(html.includes('aria-label="Close settings"'));
-		for (const id of ["general", "agent", "appearance", "graph", "keyboard"]) {
+		for (const id of ["general", "keys", "agent", "appearance", "graph", "keyboard"]) {
 			assert.ok(html.includes(`data-testid="settings-nav-${id}"`), id);
 		}
 		// General is the landing section; the others are not current.
@@ -138,6 +139,13 @@ describe("GraphSection — the dependency ladder", () => {
 	});
 });
 
+describe("KeysSection (thin SSR)", () => {
+	it("SSR = the loading state (effects never fire)", () => {
+		const html = renderToStaticMarkup(<KeysSection />);
+		assert.ok(html.includes("Loading keys…"));
+	});
+});
+
 describe("AppearanceSection (thin SSR)", () => {
 	it("mode is rendered DISABLED — dark-only this wave, no lying control", () => {
 		const html = renderToStaticMarkup(<AppearanceSection appearance={undefined} onSectionChange={() => {}} />);

tests/settings-pure.test.ts

@@ -10,6 +10,8 @@ import { describe, it } from "node:test";
 import { appearanceVars, derivedPalette, resolveAppearance } from "../components/settings/appearance.tsx";
 import { composePromptSwitch, composeRoleModel, composeTool } from "../components/settings/agent-section.tsx";
 import { nextOverrides } from "../components/settings/keyboard-section.tsx";
+import { classifyKeys, keyStatusLine, type ProviderKeyInfo } from "../components/settings/keys-section.tsx";
+import type { AuthKeyStatus } from "../src/core";
 
 describe("resolveAppearance — delta over factory", () => {
 	it("absent everything = the factory view", () => {
@@ -136,4 +138,76 @@ describe("nextOverrides — the rebind persistence map", () => {
 		const next = nextOverrides({ "toggle-sidebar": "mod+b", find: "mod+f" }, "toggle-sidebar", null);
 		assert.deepEqual(next, { find: "mod+f" });
 	});
-});
+});
+
+describe("classifyKeys — the Keys section's two-group projection", () => {
+	const synth = (id: string, present = false): AuthKeyStatus => ({
+		id,
+		info: null,
+		present,
+		masked: present ? `…${id.slice(-4)} (32 chars)` : null,
+		source: present ? "file" : "none",
+		shadowedByEnv: false,
+	});
+	const providers: ProviderKeyInfo[] = [
+		{ id: "groq", envVar: "GROQ_API_KEY", label: "Groq" },
+		{ id: "deepseek", envVar: "DEEPSEEK_API_KEY", label: "DeepSeek" },
+		{ id: "openrouter", envVar: "OPENROUTER_API_KEY", label: "OpenRouter" },
+	];
+
+	it("OpenRouter is pinned: synthesized when absent (first boot), found when present", () => {
+		const none = classifyKeys([], providers);
+		assert.equal(none.openrouter.id, "OPENROUTER_API_KEY");
+		assert.ok(!none.openrouter.present);
+		const stored = classifyKeys([synth("OPENROUTER_API_KEY", true)], providers);
+		assert.ok(stored.openrouter.present);
+	});
+
+	it("stored provider keys land in providerRows with their provider entry", () => {
+		const out = classifyKeys([synth("GROQ_API_KEY", true)], providers);
+		assert.equal(out.providerRows.length, 1);
+		assert.equal(out.providerRows[0]!.provider?.id, "groq");
+		// the Add dropdown no longer offers groq
+		assert.ok(!out.addable.some((p) => p.id === "groq"));
+		assert.ok(out.addable.some((p) => p.id === "deepseek"));
+	});
+
+	it("curated tool ids always render (synthesized when absent)", () => {
+		const out = classifyKeys([synth("DEEPGRAM_API_KEY", true)], undefined);
+		assert.deepEqual(out.toolRows.map((r) => r.id), [
+			"DEEPGRAM_API_KEY",
+			"GOOGLE_SEARCH_API_KEY",
+			"GOOGLE_CSE_ID",
+		]);
+		assert.ok(out.toolRows[0]!.present);
+		assert.ok(!out.toolRows[1]!.present);
+	});
+
+	it("unknown file vars surface read-only, out of the provider rows", () => {
+		const out = classifyKeys([synth("PLANS_LOGIN_TOKEN", true)], providers);
+		assert.equal(out.unknownRows.length, 1);
+		assert.equal(out.providerRows.length, 0);
+	});
+
+	it("providers seam absent = addable empty, nothing crashes", () => {
+		const out = classifyKeys([], undefined);
+		assert.deepEqual(out.addable, []);
+	});
+});
+
+describe("keyStatusLine — the masked at-a-glance state", () => {
+	it("present file key: tail, chars, source", () => {
+		assert.equal(
+			keyStatusLine({ id: "X", info: null, present: true, masked: "…ab12 (64 chars)", source: "file", shadowedByEnv: false }),
+			"…ab12 · 64 chars · saved",
+		);
+	});
+
+	it("env-sourced key reads 'environment'", () => {
+		assert.ok(keyStatusLine({ id: "X", info: null, present: true, masked: "…ab12 (64 chars)", source: "env", shadowedByEnv: false })?.endsWith("environment"));
+	});
+
+	it("absent key has no line", () => {
+		assert.equal(keyStatusLine({ id: "X", info: null, present: false, masked: null, source: "none", shadowedByEnv: false }), null);
+	});
+});