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 full-flow page: a selected plugin command sits over a dimmed realistic thread, ⇧⌘P remains visible as a replayable entry point, and running the action closes the palette and opens the plugin's selected Release checklist side-panel tab. The action row and numbered annotation remain distinct click targets. 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 compact Previous/Next controls to each open card's header.
• 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.
• Keeps the app-window fixture and every open annotation card above the fold in bb’s 980px desktop content region. On taller displays, the fixture’s blank-canvas minimum grows one-for-one from 500px to 650px and the timeline from 350px to 510px, then caps; width alone never triggers growth. Off-stage carousel pages no longer create page-level horizontal overflow, and a fitting desktop fixture no longer gets an unnecessary internal horizontal scrollbar; narrow fixtures still scroll together with their annotations.
• Adds compact Copy for agent actions. Each card writes one short, editable sentence around a structured, plugin-owned surface reference using bb's existing private clipboard/composer-mention contract; multiple copied references paste as distinct, composable pills and complete sentences.
• 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 current main: @get-bb/plugin-sdk and PLUGIN_SDK_VERSION are 0.4.18, advanced by Handle reserved plugin CLI name collisions #2411 for corrected CLI-collision JSDoc. This PR's cumulative diff adds no public Plugin API member and no compatibility-version bump; the Guide engine floor remains capability-based at >=0.4.3. 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: bd991315a73abd9cc5fb31bdb19e81b7f72d9f91; current main / merge base: ca0f85c44859a34f85840824de3ea9ffbccbcec8.

• Plugin Guide/API-map tests — 72/72 PASS, including deterministic fixture fidelity, responsive ownership, annotation rules, command-palette interaction, API inventory drift, reference creation, clipboard framing, and multiple distinct pills.
• Focused app tests — 50/50 PASS for UI-anatomy drift, structured mention clipboard serialization/paste, clipboard helpers, and plugin frontend reload behavior.
• Server plugin/compatibility tests on Node 22 — 29/29 PASS, including a real persisted 0.4.8 scaffold upgrading under current 0.4.18.
• Turbo typechecks — PASS for @bb/plugin-api-map, bb-plugin-plugin-api-docs, @bb/app, @bb/server, and @get-bb/plugin-sdk.
• Frozen workspace install and production Plugin Guide build — PASS. The exact-branch web bundle reports SDK 0.4.18; the Nightly path build remains compatible with its shipped SDK 0.4.8.
• git diff --check origin/main...HEAD — PASS. The cumulative diff contains no packages/plugin-sdk or SDK-version-source files, no Inspector/Moss paths, and no rejected experimental API identifiers.
• Exact-head Google Chrome for Testing 151.0.7922.71 — PASS across all seven Guide pages at 390×844, 768×900, 1440×900, and 3440×1440, adjacent transition widths, and five complete page cycles. App-window height checkpoints pass at 2048×1028 (500px minimum), 2048×1100 (572px), 2048×1188 (650px cap), and 3440×1440 (cap retained); all 13 cards remain above the fold with zero page overflow at the compact reference.
• Exact-head Safari 26.5.2 — PASS across all seven Guide pages at actual CSS viewports 2048×1028, 1440×948, 768×848, and 2048×1440 through first paint, hard reload, and five complete page cycles. The 572px intermediate minimum and 650px cap match Chrome, with the open card fully visible and zero page overflow.
• Exact-head CI — 13 checks succeeded with two expected skips in CI, Mobile E2E, and both version/SDK gates.
• No additional code review was run: the PR's one allowed review budget is exhausted. GitHub has no reviews, comments, or unresolved review threads.

Exact-head fluid Chrome evidence · Exact-head fluid Safari evidence

Before and exact-head after

Before — prior PR head 19ab9339bbd38cda4343620a4124c9ee0ac0ec1c: the app-window page overflows horizontally and vertically at the same 2048×1028 viewport

After — exact final candidate bd991315a73abd9cc5fb31bdb19e81b7f72d9f91: the compact reference still fits above the fold with no page overflow

On a taller display — the fixture restores its roomy original size and stops at the cap

Safari 26.5.2 — the same exact-head full-size cap

Earlier feature evidence

These flows were captured at prior frozen candidate 19ab9339bbd38cda4343620a4124c9ee0ac0ec1c; the final viewport-only commit does not change their contracts or interactions.

Before — right-panel annotation badges obscure their entry points

Prior candidate 19ab9339bbd38cda4343620a4124c9ee0ac0ec1c: annotations remain clear of realistic tabs

Safari 26.5.2 — prior candidate

Before — the command palette sits on an empty canvas

Prior candidate: realistic thread context, entry hint, selected plugin action, and annotation

Before — copied references paste as standalone pills

Prior candidate: two distinct pills retain short editable framing copy

Safari 26.5.2 — structured framed paste

No linked issue.

BB-Thread-ID: thr_7dczktandc

BB-Thread-ID: thr_7f4g7pd89a

AGENT GENERATED: by GPT-5.6-Sol