Onboarding tour for model selection, effort tiers, and token economics on Pro plan

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

On the Pro plan, weekly token limits are tight, and several Claude Code behaviors silently burn through budget in ways new users have no way to discover until they hit 100% exhaustion mid-task. There's currently no onboarding that explains how model selection, effort tiers, session classification, or auto-switching interact with the token cache.

I personally went from 75% → 100% exhausted on a single "remove the sound effect" prompt because the model had silently auto-switched from Opus 4.6 to Opus 4.8 in the background, invalidating my conversation cache. I only learned what was happening by asking Claude directly in a long debug conversation — which itself cost tokens.

Proposed Solution

Concrete things users don't know

1. Model switching invalidates the prefix cache. Changing model mid-session forces a full uncached replay of the conversation history. On a long coding/design session this can be 50k–150k tokens billed at full price.
2. Effort switching also invalidates the cache. Same mechanism — effort is part of the request config. Toggling Medium → Extra → Medium during one session causes two full cache rebuilds.
3. Effort tiers have a 2–3× cost spread. Extra effort on Opus 4.7 can burn tokens faster than Opus 4.8 on default. Most users assume "stronger model = more expensive" and don't realize the effort dial is the bigger lever.
4. Auto-switch-if-flagged is on by default and silently upgrades you to a more expensive model. There are two toggles (local + account-level) and most users never find them.
5. "Classify session states" runs an inference call on every session to label it blocked/ready/done — billable, on by default, and pointless if you don't use the labels.
6. All Opus models (4.6, 4.7, 4.8) share identical per-token pricing ($5/$25 per MTok). Users assume the newer number is more expensive and pick 4.6 thinking they're saving money, when the real saving comes from disabling auto-switch and picking the right effort tier.

Proposed solution

A 60-second click-through onboarding tour on first launch (and accessible later via /help or a "Token tips" menu item), with tooltips on the actual UI controls:

• Model selector tooltip: "Switching mid-session invalidates your cache and re-bills the conversation history. Pick once per session."
• Effort selector tooltip: "Effort has a bigger cost impact than model choice. Medium is the right default for routine work; Extra is 2–3× the token cost. Pick once per session."
• Auto-switch toggles: Surface both toggles in the same place with a clear "this can silently upgrade your model" explanation. Consider making them off by default for Pro users.
• Session classification toggle: Show the per-session token cost and label it as opt-in for Pro users.
• A small "session cost" indicator in the status bar would let users see in real time when something invalidated the cache.

Why this matters

Pro users are the most price-sensitive cohort and the most likely to burn out of budget. Right now the app's defaults work against them silently, and the only way to learn the rules is to exhaust your weekly limit and ask Claude what happened. A short upfront tour would dramatically improve the Pro experience and reduce frustration-driven churn.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

_No response_

Additional Context

_No response_