Take bb's public APIs where they exist

[ariofrio]

Eight commits that take bb's documented APIs everywhere these plugins had been reaching around them. No behavior changes — this is about how much of bb's insides three plugins hold onto while doing the same job.

This is the first phase of a coupling audit across all five plugins. The audit classified every call against bb's own builtin-skills/bb-plugin-authoring/SKILL.md: public (documented there), experimental (the experimental_-prefixed surface it documents but marks "Experimental: see docs/api_to_audit.md"), and private (real, undocumented, ours to lose). This PR is only the private→public moves that were available today.

Why this matters

The private surface is the part that breaks on a bb upgrade, silently and at a distance — a renamed data-testid, a localStorage key that grows a field, a route that moves. Three of these were worse than the average:

• Icons was making an authorization decision by string comparison. Which project the user may not restyle was id === "proj_personal". That literal lives in bb's packages/domain/src/project.ts; no public API promises it.
• Two plugins were parsing bb's keybinding table out of a route the plugin contract never points a plugin at, so they carried hand-rolled guards for a shape they don't own.
• Thread stages was arranging bb's own state behind its back — writing bb.root-compose.project-id, dispatching a fake StorageEvent so bb's jotai atom would notice, then synthesizing bb's New thread keystroke. Three private steps to say "compose here."

What changed

commit	private → public
Ask bb which project is personal	"proj_personal" → project.isPersonal from the sidebar SDK
Save our settings through the SDK, not the endpoint	browser PUT /api/v1/plugins/…/settings → bb.sdk.plugins.updateSettings
Let bb call the Icons plugin for us	browser fetch of a neighbour's rpc route → bb.sdk.plugins.callRpc
Let bb start the side chat for us	same, for the builtin side-chat plugin's createSideChat
Read bb's keybindings the way bb offers them	fetch("/api/v1/system/config") in both plugins → bb.sdk.system.config()
Ask bb to open the composer where the chord lands	compose-key write + StorageEvent + synthetic keystroke → openNewThread({ projectId, focusPrompt })
Let bb say which project is personal	Icons' fixed-icon rule → a project's kind, resolved once per run
Note the API move for the next release	changeset, patch for all three

Two things a reviewer should push on

Every settings and cross-plugin call gained a server hop. useSettings() reads but never writes, and there is no cross-plugin call on the app side at all — plugins.updateSettings and plugins.callRpc exist only on bb.sdk. So each of these adds a thin RPC on our own server that makes the public call. That is a round trip we did not pay before, on user-initiated actions only (saving a setting, loading icons, starting a side chat). I think a documented call is worth a loopback hop; if you disagree about listProjectIcons in particular — it runs on every sidebar project-set change — that is the one to argue about.

The compose bridge has a fallback, and the fallback is still private. openNewThread is a hook; stage chords run in a content script, where hooks do not reach. The mounted sidebar list publishes the bound action into a module-level slot and the chord calls it. When the list is not mounted — someone switched bb.sidebar.threadListProvider back to bb's own list — the chord falls back to bb's New thread command, so the composer still opens, just wherever bb left it rather than in the personal project. The alternative was keeping the private path as the fallback, which preserves the old behavior exactly and preserves the coupling exactly. I chose the degradation, and that is now a decision rather than a discovery: it is documented in the plugin's README next to the sentence that promises where the chords take you, and in the changeset that ships it.

What stays private, deliberately

Missing keyboard shortcuts still writes bb.root-compose.project-id itself: it has no persistent React surface to borrow a hook from, and useBbNavigate().toCompose() takes no projectId. Also untouched, because bb offers no equivalent: thread sections have no reorder anywhere in the SDK, REST, or CLI; there is no way to invoke a bb command (only to read the table, which this PR makes public); PluginContentScriptContext hands a script no navigation handle; no slot targets the thread header's title or a sidebar group label; and useRealtime hard-filters on the calling plugin's id, so the cross-plugin bb.icons broadcast channel has no replacement.

Those are the intended contents of a shim library, and — more usefully — the intended contents of five upstream API requests.

Verification

• npm run release:check in each touched plugin: thread-stages, missing-keyboard-shortcuts, icons — all exit 0 (lockfile verify, tests, typecheck, verify:types, build, verify:package).
• Root npm test: 27 pass, 0 fail.
• Thread stages: 228 tests, up from 208. Every commit here is red-green; setWorkflowStage gets its first behavioral test, covering the personal-project routing rule.

check:screenshots will be red

The lock hashes each plugin's src/, so any source change stales its shot even when no pixel can move. This branch stales thread-stages, icons, missing-keyboard-shortcuts, and collection. Recapturing needs macOS and the bb desktop app; happy to run npm run screenshots and push the result onto this branch before merge.

---

Review round (three blind reviewers + one runtime report)

Three reviewers read this branch without my rationale, and a fourth thread hit the same defect from the other end while investigating why npm run screenshots was hanging. All four landed on one bug.

e33e14f dropped a call. The old createSideChat made two round trips — fork the thread through the Side chat plugin, then persist the panel tab through this plugin's ensureSideChatTab. The rewrite kept only the first, so the tab was written to localStorage and nowhere else. bb rebuilds a thread's panel from its own server-side tab list (reconcileFixedPanelTabsState), and it commits Info/Git-diff tabs the first time any thread is opened — so the local list never wins and the side chat's tab was dropped on every thread, sometimes before its composer was focused. It also blocked the screenshot harness at shot 5 of 6, which is why no full capture existed on this branch.

Fixed by moving the persist inside the server's createSideChat, with a regression test on the handler. The orphaned ensureSideChatTab is gone, and validateSideChat's cleanup prunes rows that exist again.

Four more findings fixed in the same pass, none of them broken today:

finding	fix
A chord mutated before it could fail — a failed project lookup left the thread filed and the caller told it failed	routing resolves before the move; test asserts the stage is unchanged and no signal fires
Keybinding mirrors validated bb's table as one array; one changed row would silently revert the shortcut to a hardcoded default	rows are read one at a time, matching the delegate that consumes them
The mirrored Icons schema pinned fields that plugin owns; a grown row cost every icon	per-row filter behind a loose envelope
Drawing icons became a call that can fail; listIcons could reject outright	the read path degrades to "personal project unknown", the write path still refuses
updateSettings accepted 2 of the plugin's 6 settings	all six, plus a test holding the RPC's keys to the plugin's own

engines.bb checked, not bumped. Every API this branch newly uses — isPersonal, openNewThread, projects.list({includePersonal}), plugins.callRpc, plugins.updateSettings, system.config — exists at desktop-v0.35.1, the oldest tag at or below both declared floors.

Known and deliberately left: while the icons load, the personal project renders as an ordinary editable row and its picker's first pick is refused server-side. It self-corrects on the first response.

_{Written by Claude}