Skip to content

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

Closed
brsbl wants to merge 60 commits into
bb/setup-tracking-thr_gt5eeahuymfrom
bb/tips
Closed

brsbl wants to merge 60 commits into
bb/setup-tracking-thr_gt5eeahuymfrom
bb/tips

Conversation

@brsbl

@brsbl brsbl commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

Human comments

What was wrong

Users had no contextual way to discover existing bb features while starting a task.

What changed

  • A built-in Tips plugin shows three illustrated, actionable suggestions under the desktop composer after setup and the first thread.
  • The feed rotates across visits, retires used features, previews prompts on hover, and confirms actions inside the clicked card.
  • Hide tips offers Undo; new installs default on, existing installs default off, and explicit choices persist.
  • bb tips and matching plugin RPCs expose the catalog, feed, hide, dismiss, and reset controls.
  • Strictly allow-listed, anonymous tip_shown and tip_used events respect usage-sharing preferences.
  • Generic experimental composer/navigation APIs and homepage setup state support the plugin; Plugin SDK is 0.6.41.
  • The branch now uses setup tracking and shared UI, with inherited notification-card code and event declarations removed.

How you verified

  • Merge commits preserve branch history and the feature-only diff over the new setup-tracking base.
  • Remote CI passed on 08e780c8165cdae3d6231227a0a90caae899547f: CI run.
  • Current-head review, browser QA, refreshed screenshots, and user screenshot sign-off remain pending.

Previous candidate evidence — superseded

These captures document the earlier candidate and do not verify or request approval for the new head.

Before: b75017c (#5222 head) · After: eea8cbc · Captured at 2×

Branch web dev app, fresh mktemp -d data dir shared by both revisions: seeded threads, setup skipped, orbital selected, Tips switched on.

Screen / state Viewport Before After
New thread / feed at rest, light Desktop · 1440×900 Before: new-thread page without tips After: three tips under the composer
New thread / feed at rest, dark Desktop · 1440×900 Before: new-thread page without tips, dark After: three tips under the composer, dark
Tip hovered: illustration settled, placeholder preview (no tips on base) Desktop · 1440×900 Before: new-thread page without tips After: hovered tip with its illustration settled and the prompt previewed as the composer placeholder
After clicking a prompt tip (no tips on base) Desktop · 1440×900 Before: new-thread page without tips After: composer filled with the tip prompt and Added to the composer in the card
After Hide tips (no tips on base) Desktop · 1440×900 Before: new-thread page without tips After: Tips hidden confirmation with Undo

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

@chatgpt-codex-connector

Copy link
Copy Markdown

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.

brsbl and others added 4 commits October 5, 2026 22:20
Add two experimental BbNavigate methods so plugin UI can send people to
bb's own pages and commands without plugin-specific core code:

- experimental_openAppRoute(path) navigates to a same-origin in-app route
  (query and hash kept) and refuses absolute, protocol-relative,
  backslash, control-character, and /api paths.
- experimental_runAppCommand(commandId) dispatches a built-in app command
  such as palette.open or thread.search through the normal handler chain
  and returns false for unknown or plugin ids.

PluginHomepageSectionRegistration.title becomes optional; the host skips
the heading when it is absent so a section that renders nothing leaves no
orphan heading. The SDK test harness records both intents, and the SDK
version moves to 0.6.24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…page

Tips renders a single quiet tip below the new-thread composer, picked from
a typed catalog of bb core features, built-in plugins, and "ask bb to..."
workflows. Each tip has a priority, a one-sentence body, an optional
one-click action (fill the composer, open a bb page, or run an app
command), and an eligibility predicate over local signals: thread and
finished-thread counts, child and automation threads, providers in use,
installed and enabled plugins, the app version, the client surface and OS,
and observed rate limits and queued follow-ups.

At most one new tip appears per day. Dismissing retires a tip for good; a
tip also retires once its action is taken, once its feature is seen in
use, or after two shown days. What's new shows once per version after an
upgrade. State and shown/dismissed/acted counts live in plugin kv storage;
nothing is sent anywhere.

bb tips [--all] [--json], bb tips dismiss <id>, and bb tips reset mirror
the current/dismiss/act/list/reset plugin RPC methods. The plugin is
bundled and enabled by default with a Show tips switch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rename the bundled Tips plugin to bb--tips under the bundled-plugin prefix
reservation, and accept only palette.open, thread.search, and settings.open
in experimental_runAppCommand so plugins cannot run state-changing commands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…view

Tips now shows a desktop gallery of three tiles under the root composer:
each tile has a small theme-token scene that rests on its end state and
replays on hover or focus, a title, one line of copy, and its outcome
("Adds prompt" or the destination label). Hovering a prompt tip previews
its prompt as the composer placeholder; clicking fills the composer,
moves any existing draft into the prompt's trailing "Task: " slot, and
focuses the caret at the end. One "More ideas" button rotates the set
and one menu hides tips for today or turns them off. The section renders
nothing on phones, in the compact layout, or when the page is too narrow
for three tiles.

The engine picks three eligible tips per day, ordered by threads waiting
on the user, a recent rate limit for Account Pooler, and per-project
subthread and automation usage, then by fewest shown days and priority.
More ideas rotates through unseen tips before wrapping. Tips without an
action are gone. `bb tips` marks the three showing today and gains
`more` and `hide [--undo]` for parity with the UI.

Adds the experimental `useComposer().experimental_setPlaceholderPreview`
SDK API, scoped to the calling surface and released on unmount, with
audit, Plugin Guide, and harness coverage. The prototype stories move
into the plugin as visual coverage of the production gallery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brsbl and others added 2 commits October 5, 2026 22:29
Account Pooler's tip no longer filters by provider id, which the
provider-literal ratchet forbids outside provider plugins: it shows after
any rate limit or heavy use while Account Pooler is installed but off.
The reset RPC handler returns a literal `ok: true`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brsbl brsbl changed the title Add a Tips plugin with one contextual tip on the new-thread page Add a Tips plugin with three contextual tips under the new-thread composer Oct 6, 2026
brsbl and others added 12 commits October 5, 2026 22:53
…tories

Tiles lose their "Adds prompt", destination, and "In composer" rows; the
whole tile stays the button and its accessible name still says what it
does ("Adds prompt to composer", "Opens settings: Get the app"). The tile
is shorter, and the section sits a further mt-6 below the composer so it
reads as its own section. The gallery header and grid are exported so
the new Ladle stories can compose two written-tip explorations (a quiet
tip line above the header, or the tip as the header) next to the
production layout, rendered under the real new-thread composer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The scene graphics are gone: each card is just a title and a muted body,
with generous padding and a hover/focus fill, still one button with its
action in the accessible name. Long tip bodies are tightened so they fit
in three lines. The "Try with bb" label is removed; the section is named
"Tips" for assistive tech, and More ideas plus the menu sit right-aligned
in a slim row below the cards, sharing it with the status line. The
plugin's scene-only story is deleted, and the app story now compares the
production cards with a borderless text-only exploration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every catalog tip now carries a bb icon name, returned in the tip view
and rendered in a small muted chip above the title. Cards sit on the
raised surface token with the hairline border and the theme's xs shadow,
stepping to the sm shadow on hover or focus (transition only when motion
is allowed). The borderless Ladle exploration is gone; the Control story
renders the production cards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The homepage section slot sits in a content column that does not fill the
page height, so a plugin cannot anchor itself to the bottom of the empty
area. Tips instead takes a larger fixed gap (mt-28 on top of the host's
mt-6, about 136px), which keeps the cards in the lower half of the
composer area without adding a scrollbar at 1280x720 through 1440x1000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Cards use the page background, like the composer, with the hairline
border and xs shadow, and take the raised surface fill only on hover or
focus. The icon chip steps down from muted to the recessed surface tint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two Ladle-only variants of the New thread tips render a small living
diorama at the top of each card, in the same layout as production: cut
paper on kraft stock, or polished objects on a lit stage. Scenes cover
subthreads, setup, phone, split panes, the morning digest, and Browser
Automation, with slow idle motion and pointer parallax that stop under
reduced motion. Production cards are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Story C drops the card chrome: each tip is a small neutral object
standing on the page with a soft contact shadow, title and body beneath,
and the whole column as the button with a hover fill and focus ring.
Objects are still at rest and play a short settle with light parallax
only on hover or focus, static under reduced motion, with at most one
small accent each. Production cards are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every catalog tip now carries a tone (blue, green, amber, orange, or
rose), returned in the tip view. The icon chip takes a 14% tint of that
theme accent and the icon mixes the hue with ink, keeping icon contrast
above 5:1 in light and dark; rose is a muted blend of the destructive
and timeline accents so it never reads as an error. The cards are
otherwise unchanged. Ladle keeps both candidates (tinted chips, and
tinted chips with a corner wash) next to the production story.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each catalog tip now draws its own 44px inline SVG, a tiny product
sketch of the idea (subthreads branching, a settings panel, a phone
thread list, split panes, an envelope digest, decision buttons, and so
on), in one line-and-wash style with ink strokes and a single small
accent from the tip's tone. The tinted chip and the Hugeicons icon field
are gone. The illustrations are decorative and static. Ladle drops the
chip candidates and adds a sheet of every tip's illustration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The three tips now stack as rows in one hairline-divided container under
the composer, each with its illustration on the left and title and body on
the right; the whole row is the button and keeps the hover fill, prompt
preview, and click-to-fill. "More ideas", the overflow menu, the more RPC,
and `bb tips more` are gone; the daily set still rotates unseen tips first.
A low-key "Hide tips" button above the feed turns tips off with an inline
Undo that points to the Show tips setting.

The Show tips setting no longer has a 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, saves that 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. `bb tips` says when tips are off
and how to turn them on.

The illustrations render at 64px with lighter strokes and more fill, and
Run work in parallel, Build a tool, and Command palette are redrawn to read
clearly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brsbl brsbl changed the title Add a Tips plugin with three contextual tips under the new-thread composer Add a Tips plugin with a feed of three contextual tips under the new-thread composer Oct 6, 2026
brsbl and others added 3 commits October 6, 2026 04:16
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
At rest every illustration is unchanged and still. Hovering or
keyboard-focusing a row acts out its tip in one short pass (bars fill,
toggles flip and the slider glides, a new row slides into the phone,
panes light up, the digest rises, the cursor taps and checks, the clock
hand turns, the palette key presses and results appear, bars grow, the
tool snaps in, the sparkle twinkles) and holds the end state; leaving
eases back. Only the hovered row moves, everything is CSS transforms
and opacity, and reduced motion turns it off. The Illustrations story
plays each drawing on hover or focus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each new visit to the New thread page adds one tip at the top and drops
the oldest, cycling the eligible library unseen-first. Clicked tips skip
the next visit; tips for features already in use retire. The feed fades
at the bottom.

Tips now follow a validated schema with a source, version, review, and
expiry fields, and a closed set of action types run from one module.
Illustrations are built from a shared diagram kit with named hover
animations, shown in new Ladle stories. AUTHORING.md and a repo-local
tips-authoring skill describe how to add a tip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brsbl brsbl changed the title Add a Tips plugin with a feed of three contextual tips under the new-thread composer Add a Tips plugin with a fresh feed of contextual tips under the new-thread composer Oct 6, 2026
Branch's from prop collided with the kit's animation from offset, so its
endpoints are now start and end. The server tests now expect a refill
at the top of the feed and check per-project eligibility on a first
visit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brsbl and others added 2 commits October 8, 2026 11:59
… record onboarding events

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brsbl and others added 8 commits October 8, 2026 17:32
Each tip now has a tier: 1, 2, 3, or unranked, based on which early
behaviors go with people sticking with bb. The feed shows tier 1, then
unranked, then tier 2, then tier 3; boosts and priority only reorder
tips inside a tier, and tier 3 appears only after higher tiers have all
been shown. Automations lead the unranked tips.

Adds tips for a second agent on the same task, adding a second agent,
bb connect, and the bb CLI, with illustrations from the diagram kit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The mobile app, bb connect, first plugin, and second agent tips now fill
the composer with a prompt asking the agent to walk the person through
setup one step at a time, as an interactive answer when that tool is
available and as numbered steps otherwise. The wording lives in
walkthroughPrompt(), documented in AUTHORING.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-notification-opt-in-onboardin-thr_7xet9fqq42

# Conflicts:
#	apps/app/src/components/onboarding/Onboarding.stories.tsx
#	apps/app/src/components/onboarding/OnboardingGate.tsx
#	apps/app/src/components/onboarding/SetupChecklistHost.test.tsx
#	apps/app/src/components/onboarding/SetupChecklistHost.tsx
#	apps/app/src/components/plugin/PluginNewThreadComposer.test.tsx
#	apps/app/src/views/RootComposeView.tsx
#	packages/domain/src/plugin-sdk-version.ts
#	packages/plugin-sdk/package.json
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A notifications tip appears only when push notifications are on, browser
permission is still undecided, and the sidebar notification prompt has
already been answered; it opens the push notifications plugin. A tier 3
tip points to the plugin store, featuring Browser Automation. The
walkthrough prompts now use shorter goals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#5222 removed the setup checklist and banner after #5291 and added
useSetupComplete: the setup guide is finished or skipped and at least
one thread exists. Home sections now get experimental_setupComplete
from that hook. Plugin SDK moves to 0.6.39, one above the base's 0.6.38.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…igator

The merged useBbNavigate now needs a query client, so the navigation
test renders inside one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es hierarchy, one done treatment, new plugin list

- Agent step names the checked machine when it isn't this computer; new ACP footer line
- Projects: new repos first with a quiet selection header, already-added repos as a checked group, subtitle matches the 7-day preselection
- Devices: mobile app as the primary card with one Get the app action, browser access and another machine as secondary rows, footer button Start your first thread
- Plugins: Workflows, Browser Automation, Agent Annotations, GitHub, Ask User Question, File Editor with first-session descriptions
- Shared done mark (diff-added green) for header steps, ready agents, connect On and added repos; Agent step label is Agents
- Notification card copy; step_reached counts once per step and leaving the Devices route counts as skipped

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brsbl and others added 13 commits October 9, 2026 19:41
The parallel-work and second-agent tips now say what the person gets
instead of naming child threads. AUTHORING.md's voice rules say to use
bb UI terms only when pointing at that UI or telling the agent which
feature to use, and a catalog test keeps titles and bodies free of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e room

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Plugin SDK moves to 0.6.41, one above the base's 0.6.40.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The feed is now a SuggestionSection labelled Tips holding a
SuggestionGroup of SuggestionCard rows, with each tip's illustration as
the leading node. A click confirms inside the clicked card with
InlineConfirmation instead of a separate status line, and Hide tips
confirms in place with Undo. The local row styles and bottom fade are
gone; AUTHORING.md points to the shared components.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Forkable plugins import only registry components, so suggestion-card
and inline-confirmation join the plugin component registry. Walkthrough
prompts now ask for a playground, the new name for interactive answers,
when that tool is available.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…udge to the plugin registry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The plugin component registry now comes only from #5222.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brsbl
brsbl removed this pull request from stack #5232 October 12, 2026 21:28
@brsbl
brsbl changed the base branch from bb/checklist-led-home-notification-opt-in-onboardin-thr_7xet9fqq42 to bb/setup-tracking-thr_gt5eeahuym October 12, 2026 21:28
@brsbl
brsbl added this pull request to stack #5398 October 12, 2026 21:28
@github-actions github-actions Bot closed this Oct 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This is an automated message. We have closed this pull request because it has been open for more than two weeks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant