plugin-guide-maintenance

Maintain the Plugin Guide

The Plugin Guide is bb's public Plugin SDK reference. For a public API change, follow the full workflow. For annotation-only maintenance, start at Maintain annotation layout, skip the public-API section, and then follow the annotation-only verification path.

Confirm a public API change

Build the declarations and inspect the SDK change:

pnpm exec turbo run build:types --filter=@get-bb/plugin-sdk
git diff -- packages/plugin-sdk/package.json packages/plugin-sdk/src

Continue only when the API change affects a Guide card, API symbol list, or fixture. If the Guide remains accurate, do not change it.

New public members also require:

• an experimental_ name, or an Experimental type name;
• an entry in docs/api_to_audit.md;
• compatibility with released SDK users unless the user approves the break.

Find the product source

For a visible method, inspect these sources:

1. The app component that shows the surface.
2. The slot, collector, or adapter that inserts the plugin content.
3. The closest app test that defines the real states.

Record stable source paths and anchors in plugins/plugin-api-docs/src/anatomy-manifest.json. Use labels, roles, data attributes, class constants, and state names as anchors. The @bb/app tests check the anchors against the source.

For a method without a visible surface, use the Plugin backend group. Do not invent interface elements.

Add the Guide entry

For a new Guide entry, run the scaffold command with its sources and symbols:

pnpm exec turbo run scaffold:surface-entry --filter=bb-plugin-plugin-api-docs -- \
  --id <stable-id> \
  --title "<visible-product-object>" \
  --group <group> \
  --source <source-path> \
  --api-symbol <exported-name>

Complete the applicable changes:

• Update plugins/plugin-api-docs/src/surfaces.ts.
• Prefer an existing card unless the API creates a new product surface.
• Keep existing surface IDs stable and list each exact exported symbol.
• Name example plugins in firstParty by display name. A plugin missing from plugins/plugin-api-docs/src/first-party-plugins.json needs a row there; the @bb/scripts tests check each row against the plugin's manifest.
• For a visible method, update wireframes.tsx and its marker.
• Match the real ownership, labels, roles, order, states, actions, and outcome.
• Keep Guide annotations separate from the product interface.
• Add focused tests for the entry, source anchors, trigger, and outcome.