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 narrow widths, the page selector is the sole one-line horizontal scroller and automatically reveals the selected page; every spatial fixture instead scales with its annotations to fit the window without clipping or page overflow. On wider displays, fixtures restore their authored size up to the existing roomy cap.
• 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: de4804e6db63734d4e06e021ab6d5a82cfa7c19e; current main / merge base: 1f064e5a0b11d0a1e84b5fe6b3600ffc66ad9445.

• Plugin Guide/API-map tests — 72/72 PASS at the exact head, including deterministic fixture scaling, one-line page-list ownership, responsive annotation geometry, command-palette interaction, API inventory drift, reference creation, clipboard framing, and multiple distinct pills.
• Focused app anatomy-manifest tests — 4/4 PASS at the exact head; the broader structured clipboard, paste, and frontend reload coverage remains green from the preceding frozen candidate.
• 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 personal Nightly path installation was rebuilt and reloaded from the same checkout with its shipped 0.4.17 SDK stamp and remains compatible.
• 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. At 390px the 872px page list scrolls inside a 270px owner while every spatial fixture has zero inline overflow and keeps the active page visible; wide fixtures return to scale 1.
• Exact-head Safari 26.5.2 — PASS across all seven Guide pages at actual CSS viewports 2048×1028, 1440×948, and 768×848 through first paint, hard reload, and five complete page cycles. At 768px the 872px page list scrolls inside its 328px owner; every fixture fits with no page overflow and the wide reference restores scale 1.
• Exact-head CI — 13 checks succeeded with two expected skips in CI, Mobile E2E, and the 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 responsive Chrome evidence · Exact-head responsive Safari evidence

Before and exact-head after

Narrow page list and responsive fixture

Both Chrome captures use the branch web app at 390×844 on the same /plugins/plugin-api-docs/plugin-api/app-shell route, fixture data, selected page, and scroll state.

Before — prior exact PR head 05782489ae080500b5ce98a356df866e7cfd6795: page labels wrap into several rows and the desktop fixture is cut off

After — exact final candidate de4804e6db63734d4e06e021ab6d5a82cfa7c19e: the page list stays one horizontally scrollable row and the complete annotated fixture fits

Safari 26.5.2 — exact final candidate at 768×848 CSS pixels

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 latest responsive-layout follow-up 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