Add a Tips plugin with a fresh feed of contextual tips under the new-thread composer

[brsbl]

Human comments

Stack

Stacked on #5222 (setup checklist, onboarding telemetry allow-list): this PR targets bb/checklist-led-home-notification-opt-in-onboardin-thr_7xet9fqq42 and is registered as GitHub stack #5232 (#5222 → #4991). #5222's branch was merged in, not rebased; the diff against it is Tips work only.

What was wrong

bb ships faster than release notes, Twitter, and Discord can teach it. Feedback from Sep 7–Oct 4 shows people missing features that already exist (connecting Desktop to another server, Account Pooler fixing repeated Claude logouts, provider handoff), and features that help people keep using bb, like child threads, queued follow-ups, multiple providers, building a plugin, and mobile, have no in-product nudge.

What changed

• New built-in Tips plugin (bb--tips), bundled, with a Show tips setting. On desktop it shows a calm feed of three rows under the new-thread composer: one bg-background container with border-border-hairline, shadow-xs, and hairline dividers between rows. Each row has a 64px line illustration on the left (ink tones, one small tone accent, no background) and a title and one-sentence body on the right. There is no section label (screen readers hear "Tips").
• A feed that stays fresh: each new visit (a fresh mount at least 10 minutes after the last) adds one tip at the top and drops the oldest. The engine cycles through every eligible tip, unseen first, before repeating any. A clicked tip is left out of the next visit and returns only after the rest of the library has shown. Tips for features already in use retire for good. Tips are ordered by tier first, based on which early behaviors go with people sticking with bb: tier 1 (child threads, the mobile app, a second agent on the same task, asking the agent to build a plugin), then unranked tips placed by judgment with automations first, then tier 2 (bb connect, the bb CLI, more than one agent), then tier 3 (queued follow-ups), which shows only after every higher-tier tip has been shown. Inside a tier, contextual boosts (threads waiting on you, Account Pooler after a rate limit) and priority decide. State lives in plugin storage.
• Bottom fade: a theme-independent mask fades the bottom of the feed. It lifts while the last row is hovered or focused, so that row stays readable and its focus ring isn't clipped.
• Hover animation: each illustration is still at rest and plays once while its row is hovered or focused, holding the end state. Reduced motion turns this off.
• The whole row is the button: hover adds bg-surface-raised. Every click marks the tip used and announces the result in a status line. Tips use one of five action types, implemented once in plugins/tips/actions.ts:
  • prompt fills the composer, moves any existing draft into the prompt's trailing Task: slot, and focuses it with the caret at the end. Hovering or focusing a prompt row previews the prompt as the composer placeholder.
  • open-page opens a core Settings route.
  • run-command runs palette.open, thread.search, or settings.open.
  • open-plugin opens a built-in plugin's detail page.
  • learn-more opens an https:// link using the person's browser preference.
• New tips: a second agent on the same task (prompt, with two or more agents), adding a second agent (opens Settings → Providers, with one agent), bb connect (opens the built-in plugin), and the bb CLI (prompt to script bb), each with a diagram-kit illustration and hover animation.
• Typed tip schema: each tip has id, title (≤45 characters), body (one sentence, ≤110), illustration, tone, action, source (changelog, blog, guide, or feature, with a ref and optional version), addedAt, reviewedAt, optional expiresAt and held, and eligible, retireWhen, and boost predicates. Expired tips never show, and an expired tip fails CI against CATALOG_REVIEWED_THROUGH. Tests check that every illustration exists, that open-plugin targets are built-in plugins, and that open-page targets are real Settings routes.
• Diagram kit: every illustration is built from plugins/tips/diagram-kit.tsx, which has 30 primitives (Panel, Window, Rule, Dot, ListLine, Node, Branch, ProgressBar, Toggle, Slider, Button, CheckMark, Check, Cursor, Phone, Envelope, Keycap, SearchGlyph, Magnifier, ChartAxes, Bar, CardStack, Arrow, Sparkle, Bubble, Clock, CalendarGrid, Wrench, Pill, Highlight) and 16 named hover animations with a stagger prop. Ladle stories plugins/Tips → Illustrations and Diagram kit show them.
• Authoring: plugins/tips/AUTHORING.md covers fields, voice, actions, illustration rules, and a checklist. A repo-local skill, .bb/skills/tips-authoring, walks an agent through adding a tip.
• Easy dismiss: a low-key Hide tips × button above the feed (with a tooltip) turns tips off. An inline Undo explains that Show tips in the plugin settings turns them back on.
• On by default for new installs only: the setting has no fixed default. The first time Tips runs, it classifies the install once as new when it has no threads or none older than two weeks (installs with more than 200 threads count as existing). It saves that decision in plugin storage and writes the setting on for new installs and off for existing ones. An explicit choice always wins, and the saved decision never flips.
• Only after setup: Tips never appears while bb's setup banner sits above the composer. Until the checklist is finished or dismissed, the section renders nothing and makes no RPC calls, so nothing counts as shown. The new-user default and desktop-only rules are unchanged.
• Anonymous tip events: with usage data sharing on, Tips reports tip_shown once per tip per visit and tip_used on click through sdk.system.experimental_recordTelemetryEvent. Both are on Ask for notifications from a sidebar card, refocus setup checklist content, and record onboarding events #5222's strict allow-list with only tip_id (an enum of catalog ids), position (1–3), and action (prompt, open-page, run-command, open-plugin, learn-more). Unknown ids, positions, actions, or extra properties get a 400. The server drops the events when sharing is off (Settings toggle or BB_TELEMETRY=false); the plugin does not check the setting itself. The tip id enum lives in @bb/server-contract (TIP_TELEMETRY_IDS) and the plugin's TIP_IDS; the catalog's tip() helper only accepts TipId, the SDK call only type-checks with allow-listed ids, and tests fail if the catalog, TIP_IDS, and the allow-list differ. The Settings privacy description, docs/configuration.md telemetry list, getbb.app /privacy, and the Tips overview now describe these events and the opt-out.
• Spacing: the feed sits about 130px below the composer's controls row, with no scrollbar at 1280×720 or 1280×860.
• No tips on mobile or compact layouts: the plugin renders nothing on phones, below a 768px viewport, or when its section is narrower than 520px, and makes no RPC calls there. No core layout changes.
• CLI and SDK: bb tips [--all] [--json] (marks the tips in the feed, newest first, and says how to turn tips on when they are off), bb tips hide [--undo], bb tips dismiss <id>, bb tips reset, with matching plugin RPC methods. Documented in the configuration guide, guide template, and plugin skill.
• Core, generic and experimental (each with a docs/api_to_audit.md entry and a Plugin Guide surface; plugin SDK 0.6.35):
  • Home-screen sections receive an optional experimental_setupComplete prop. Core derives it once in useSetupChecklist from the same state that renders the setup banner, and passes it through RootComposeSecondaryContent to PluginHomepageSections. It is false before onboarding finishes, while any item is open, and while setup data loads. No Tips-specific core code.
  • useComposer().experimental_setPlaceholderPreview(text | null) sets a temporary placeholder on the composer; it clears when the caller unmounts, and the accessible label keeps bb's own placeholder.
  • useBbNavigate().experimental_openAppRoute(path) accepts in-app paths only. Absolute URLs, protocol-relative paths, backslashes, control characters, and /api routes are refused.
  • useBbNavigate().experimental_runAppCommand(id) accepts only palette.open, thread.search, and settings.open.
  • Homepage sections may omit title; older hosts are protected by engines.bbPluginSdk >=0.6.35.

Owner decisions

• Account Pooler tip is live. Open pooler issues (Account Pooler prevents Claude in Chrome tools from loading despite --chrome #4707, Account Pooler blocks Claude extra usage when subscription quota reaches the switch threshold #4475, Account Pooler bills Fable to a Team account's extra usage while a pooled Max account includes Fable #3615, Show pooled Claude and Codex account usage in Settings → Usage #3243, and the unretried 429) may argue for holding it; set held: true in plugins/tips/catalog.ts.
• SDK version: this layer bumps the plugin SDK to 0.6.35, one above its base Ask for notifications from a sidebar card, refocus setup checklist content, and record onboarding events #5222 (0.6.34). If another PR takes 0.6.35 first, this layer moves to the next free version.

How you verified

• Tests cover the per-visit feed (the 10-minute debounce, insert at the top, clicked tips replaced on the next visit, cycling the library), retirement and dismissal, contextual ordering, held and expired tips, the tip schema and catalog targets, every action type and its announcement, new vs existing classification, explicit setting overrides, the persisted decision not flipping, Hide tips with Undo, compact and mobile hiding, the placeholder preview API, the CLI, and both navigation APIs.
• Tests also cover the setup gate (useSetupChecklist().setupComplete is false while the banner shows, while setup loads, and before onboarding finishes, and true after dismissing or finishing every item; homepage sections receive it; Tips renders nothing and makes no calls until it is true) and telemetry (the route accepts both tip events and rejects other ids, positions, actions, and extra properties; the allow-list matches the catalog; Tips sends each shown tip once per visit and each click with position and action, and nothing for unknown ids).
• Setup gate: branch web dev app at the merge of Ask for notifications from a sidebar card, refocus setup checklist content, and record onboarding events #5222 28d23b0 (banner-only checklist), fresh mktemp -d data dir with a small seeded project and finished threads, Chrome for Testing via Browser Automation, 1280×860 at 2×. After first-run onboarding was skipped, the setup banner showed above the composer and Tips rendered nothing and wrote no plugin state. After the banner was dismissed, the feed appeared with the orbital project selected. The seed archives its threads, so they were unarchived in that QA database first; because they are old, Tips classified the install as existing and left the switch off, so it was turned on with bb plugin config bb--tips set enabled true.

Setup unfinished: banner, no tips	After dismissing setup: tips feed

• Feed per visit (earlier pass, same branch web app, demo-app selected; later visits simulated by moving the feed's last-visit time back 11 minutes in plugin storage):

• Hover (same setup-gate session): the row plays its illustration and previews its prompt in the composer.

Known follow-ups (not in this PR):

• "Hide for today" uses the server's time zone.
• The feed follows the composer's project only when the project is in the URL.
• The feed and its visit clock are shared across clients.

BB-Thread: Brainstorm BB feature for sharing tips and
BB-Thread-ID: thr_rtj958b9wf

AGENT GENERATED

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.