Plugin Guide v1: in-app plugin API docs with SDK-synced surface map

[brsbl]

What was wrong

bb's public Plugin SDK was discoverable only through declarations and scattered implementation details. Plugin authors had no product-native map of extension points, no compact way to hand one of those surfaces to an agent, and no enforced maintenance path when the public SDK changed.

What changed

• Adds the built-in bb Plugin Guide (plugins/plugin-api-docs) backed by the shared packages/plugin-api-map package.
• Documents each plugin surface with an annotated, interactive bb UI model, capability card, authoritative SDK symbols, cross-references, and first-party usage.
• Gives command-palette actions their own page. The app-window page is larger and less cramped; its timeline and loading skeleton share taller, looser geometry.
• Makes annotations sequential on every page and adds Previous/Next controls to each open card.
• Makes app-window annotations 9, 10, and 11 behave like the entry points they describe: a thread-panel tab, a real retry-notes.md custom-viewer tab, and a realistic custom Diff tab. Their badges occupy a reserved upper lane and do not clip or cover the tabs.
• Shows the message-action hover row and its selection-toolbar state, including a distinct Stripe mock selection. Moves the composer typeahead fixture just enough to clear its annotations.
• Adds compact Copy for agent actions. Each card writes one structured, plugin-owned surface reference using bb's existing private clipboard/composer-mention contract; multiple copied references paste as distinct, composable pills.
• Adds a committed public-SDK inventory plus api-sync.test.ts, so CI fails when a public plugin export, app.slots.* method, or BbPluginApi property changes without a corresponding Guide surface.
• Ships the plugin-guide-maintenance skill with the plugin. It covers identifying SDK drift, updating the surface card and minimal agent pointers, regenerating the inventory, running focused tests/typechecks, building, and real-UI verification.
• Keeps compatibility aligned with main: @get-bb/plugin-sdk, PLUGIN_SDK_VERSION, and the Guide bundle are all 0.4.17; the Guide engine floor remains capability-based at >=0.4.3. This PR adds neither a public Plugin API nor a compatibility-version bump. The proposed experimental_pluginCustomizations and experimental_copyMention APIs are not present.
• Contains no Inspector or Moss changes and no host-daemon protocol change.

How you verified

Final pushed candidate: c83b3264ba8c623eef04a4443aef05e103ace4b1; current main / merge base: 42d2c1bec2e9830bd8e2b8f5f355ebffda37bded.

• Plugin Guide/API-map tests — 52/52 PASS.
• Focused app clipboard/composer tests — 137/137 PASS.
• Server plugin/compatibility tests on Node 22 — 29/29 PASS, including the persisted 0.4.8 scaffold upgrade regression against 0.4.17.
• Turbo typechecks — PASS for @bb/plugin-api-map, bb-plugin-plugin-api-docs, @bb/app, and @get-bb/plugin-sdk.
• Production Plugin Guide build/reload — PASS; live bundle metadata reports SDK 0.4.17 and a compatible engine floor.
• git diff --check origin/main...HEAD — PASS. No Inspector/Moss paths; no experimental_pluginCustomizations, experimental_copyMention, or 0.4.18 references.
• Exact-head Google Chrome for Testing 151.0.7922.71 — PASS: 9/10/11 each have a measured 4px target gap; file and diff bodies render; all 13 app-window annotations advance in order; the command-palette page renders; two card references paste into bb's real new-thread composer as distinct pills.
• Exact-head Safari 26.5.2 — PASS: hard reload, horizontally panned wide app mockup, 9/10/11 geometry and tab bodies, all 13 annotation transitions, client navigation to the settled command-palette page, and keyboard activation of Copy for agent.
• Exact-head CI — PASS: CI run and version/SDK gates.
• No additional code review was run: the PR's one allowed review budget is exhausted.

Structured Chrome evidence · Structured Safari evidence

Before and exact-head after

Before — prior candidate: annotation badges cover the right-panel entry points

After — exact final candidate: annotations 9, 10, and 11 sit above clear, realistic tabs

Exact-head custom file viewer

Exact-head custom diff renderer

Exact-head command-palette page

Exact-head composed composer references

No linked issue.

BB-Thread-ID: thr_7dczktandc

BB-Thread-ID: thr_7f4g7pd89a

AGENT GENERATED: by GPT-5.6-Sol