fix: harden recent chat feature polish

.docs/codex-prerequisites.md

@@ -11,7 +11,7 @@ Optional app settings for Codex:
 - Override the Codex home path if you keep Codex state in a non-default location.
 - Add an OpenRouter API key if you want to use Codex with `openrouter/free` or specific OpenRouter `:free` model ids.
 - Set the default Codex service tier in Settings.
-- Use the **OpenRouter Free Models** settings card to browse the live OpenRouter entries that are both free-locked and compatible with CUT3's native tool-calling path (`tools` plus `tool_choice`), then pin them into the picker.
+- Use the **OpenRouter Free Models** settings card to browse the live OpenRouter entries that are both free-locked and compatible with CUT3's native tool-calling path (`tools` plus `tool_choice`), then pin them into the picker. If the next live refresh fails, CUT3 falls back to the last known-good compatible catalog and marks it as stale instead of collapsing the list.
 - Save extra OpenRouter `:free` model ids such as `google/gemma-3n-e4b-it:free` or custom Codex model ids if you want them in the model picker and `/model` suggestions.
 - Use the composer controls to choose Codex reasoning effort and per-turn `Fast Mode`. OpenRouter models may advertise reasoning support, but CUT3 does not expose Codex-specific reasoning-effort levels for those free models.
 

.docs/provider-settings.md

@@ -99,6 +99,7 @@ CUT3 now shows OpenRouter free models in their own settings card and their own t
 - The settings page fetches OpenRouter's live model catalog, but CUT3 only lists models that are explicitly free-locked (`openrouter/free` or `:free`) and advertise the full native tool-calling surface CUT3 needs (`tools` plus `tool_choice`).
 - You can pin any listed OpenRouter free model into the picker and `/model` suggestions with one click.
 - If the live catalog cannot be fetched, CUT3 surfaces that state in Settings instead of silently hiding it.
+- CUT3 now keeps a last-known-good compatible catalog locally, so the picker and the Settings card can continue showing the previous free-model list with a stale/offline warning instead of collapsing back to only the router entry.
 - If a pinned OpenRouter `:free` model cannot be served because the route is unavailable, overloaded, rate-limited, or filtered out by provider/privacy constraints, CUT3 automatically retries the turn through `openrouter/free` and shows a warning banner so the turn does not silently drift onto a billed model. CUT3 does not auto-retry Responses API validation failures or payment/credit errors, because those need explicit user action instead of a silent reroute.
 - OpenRouter free models still depend on OpenRouter account limits. New accounts only get a small free allowance, purchased credits raise the daily free-model limit, and negative balances can still produce `402 Payment Required` even for `openrouter/free`.
 
@@ -130,8 +131,9 @@ The chat composer now exposes a richer model picker instead of only nested provi
 
 - The picker is searchable across provider names, model labels, and raw model slugs.
 - Models are grouped by provider, with OpenRouter kept as its own top-level section.
-- `Connect provider` opens an in-chat setup panel that shows provider health, lets you add or update the shared OpenRouter key and Kimi API key, reminds you that OpenCode auth still lives in `opencode auth login` / `opencode auth logout`, and shows Pi guidance for the external `pi` / `bunx pi` + `/login` flow plus `~/.pi/agent` auth/config.
-- `Manage models` opens an in-chat model management surface with per-model visibility toggles.
+- `Provider readiness` opens an in-chat onboarding surface that summarizes local provider health, groups providers into ready / attention / unavailable states, offers copyable login commands where CUT3 knows the real CLI flow, lets you jump straight into OpenRouter/Kimi key entry, and links back to Settings for deeper runtime configuration.
+- `Manage models` opens an in-chat model management surface with per-model visibility toggles plus favorite pinning.
+- Favorites stay pinned near the top of the picker, and recent model selections are also surfaced ahead of the long tail so switching providers or models takes fewer searches.
 - Hidden models are removed from both the main picker and `/model` suggestions, but they stay saved locally so you can restore them later with `Show all`.
 
 ## Composer controls
@@ -161,6 +163,16 @@ Codex also has a per-turn `Fast Mode` toggle in the composer controls. This is s
 
 CUT3 hides the "token context left" UI for OpenRouter-routed models because the routed model can change and the remaining-context display is not reliable enough there.
 
+### Usage dashboard
+
+The composer context ring is now a full `Usage dashboard` trigger instead of only a passive status badge.
+
+- Click the context ring to open a dialog with the current selection's documented/live context window, token breakdown, latest matching runtime snapshot metadata, and latest reported spend when the provider exposes it.
+- The model picker footer also includes a `Usage` shortcut so you can open the same dashboard while browsing providers/models.
+- If the latest stored runtime snapshot belongs to a different provider/model than the current selection, CUT3 calls that out explicitly instead of silently showing stale numbers.
+- GitHub Copilot selections also include current premium-request quota information in the dashboard.
+- Cost reporting depends on the provider runtime. CUT3 shows the latest reported USD amount when the provider supplies it, otherwise the spend card stays unavailable instead of guessing.
+
 ### Image attachments
 
 The composer also supports lightweight image input:

.docs/quick-start.md

@@ -48,11 +48,12 @@ Use the matching host OS when possible. Cross-platform packaging is not the defa
 
 - Open **Settings** to configure appearance, including theme presets, per-mode palette/font controls, an English/Persian language switch, and an optional chat background image, plus provider binary overrides, OpenRouter and Kimi API keys, OpenCode binary selection, Pi guidance, model preferences, thread sharing mode (`Manual`, `Auto`, `Disabled`), and whether tool/work-log entries stay visible in the main timeline. If you use Kimi without an API key, authenticate in Kimi Code CLI with `kimi login` or the in-shell `/login` flow. If you want to use Pi, authenticate it outside CUT3 through the Pi CLI (`pi` or `bunx pi`) and `/login`, or populate `~/.pi/agent/auth.json` / provider env vars first.
 - Use **Settings > Permission policies** to save app-wide or project-scoped approval rules when you want CUT3 to automatically `allow`, `ask`, or `deny` repeated approval requests.
-- Use the **OpenRouter Free Models** card in Settings to review the current OpenRouter catalog entries that are both free-locked and CUT3-compatible, then pin any of them into the picker.
-- Save extra GitHub Copilot, OpenCode, Kimi, Pi provider/model ids, custom Codex ids, or currently listed OpenRouter `:free` model ids if you want them in the picker and `/model` suggestions.
+- Use the **OpenRouter Free Models** card in Settings to review the current OpenRouter catalog entries that are both free-locked and CUT3-compatible, then pin any of them into the picker. If the next live refresh fails, CUT3 now falls back to the last known-good catalog and labels it as stale instead of collapsing the list unexpectedly.
+- Save extra GitHub Copilot, OpenCode, Kimi, Pi provider/model ids, custom Codex ids, or currently listed OpenRouter `:free` model ids if you want them in the picker and `/model` suggestions. You can also pin favorites in `Manage models`, and CUT3 now keeps recent picks near the top of the picker so repeated model switches take fewer steps.
 - For Codex, choose a default service tier in Settings, use the top-level OpenRouter section in the model picker when you want `openrouter/free` or another current free OpenRouter model, and adjust reasoning / `Fast Mode` per turn from the composer. OpenRouter models can advertise reasoning support, but CUT3 does not expose Codex-specific reasoning-effort levels for them. Pi reasoning-capable models now also expose Pi thinking levels from the composer while leaving Pi's own default thinking untouched until you choose an override. If CUT3 has to retry a pinned OpenRouter free model through `openrouter/free`, the chat shows a warning banner instead of switching silently.
 - Put repo-local skills in `.cut3/skills/<name>/SKILL.md` with `name` and `description` frontmatter, then select them from the composer Skills picker before sending a turn.
 - Use the paperclip button, drag-and-drop, or paste to attach up to 8 images per message. CUT3 accepts image files only and limits each image to 10 MB.
+- On a fresh install with no configured projects, the empty chat view now guides you through adding your first project folder and opens the first draft thread automatically.
 - Pick `Full access` or `Supervised` in the toolbar depending on whether you want direct execution or approval-gated actions.
 - Switch between `Chat` and `Plan` when you want plan-first collaboration with the plan sidebar.
 - While a turn is running, use the composer Queue/Steer controls to line up the next follow-up. `Enter` uses the currently selected follow-up mode, and `Cmd/Ctrl+Enter` uses the opposite mode for that one message.

AGENTS.md

@@ -22,6 +22,8 @@
 - Keep Kimi auth UX aligned with the official Kimi CLI docs: user-facing guidance should mention `kimi login` and the in-shell `/login` path, plus the CUT3 Kimi API key setting, instead of assuming only one auth flow.
 - Keep Pi auth and discovery UX aligned with the real Pi surfaces: CUT3 embeds Pi through the Node SDK, but Pi credentials still live in `~/.pi/agent/auth.json` / Pi env vars or the external `pi` `/login` flow, and CUT3 should keep Pi packages, AGENTS files, system prompts, extensions, skills, prompt templates, and themes disabled so CUT3 injects workspace instructions only once.
 - Keep Pi model discovery live in the chat UI: `server.getConfig` / provider refreshes must rerun provider health, and when Pi already exposes authenticated models from local `~/.pi/agent` state, the picker and `/model` suggestions should surface those provider/model ids instead of collapsing back to a static `pi/default` placeholder.
+- Keep provider onboarding/readiness UX centralized in the chat provider-readiness surface plus shared provider health/state helpers; do not scatter provider-specific setup copy, login commands, or readiness summaries across multiple unrelated components.
+- Keep model-picker ranking state centralized through app settings + shared model-preference helpers. Favorites, recents, hidden-model state, picker ordering, and `/model` suggestion ordering must stay aligned instead of each view inventing its own ranking rules.
 - Keep Pi reasoning UX aligned with the real Pi SDK surface: CUT3 should trust Pi's live `model.reasoning` catalog flag plus `AgentSession.getAvailableThinkingLevels()` / `setThinkingLevel()` instead of hardcoding Codex-style assumptions, and should preserve Pi defaults until the user explicitly picks a thinking level override.
 - Keep GitHub Copilot reasoning UX aligned with the real CLI/ACP surface: current Copilot CLI builds expose `xhigh` reasoning for some models, so contracts, probes, and composer docs must not clamp Copilot to only low/medium/high.
 - Keep GitHub Copilot model slugs aligned with live ACP session metadata. Do not hard-code blanket slug rewrites; mirror whatever the runtime actually advertises, and treat stale picker-only entries that never appear in live Copilot/OpenCode model catalogs as bugs.
@@ -33,6 +35,10 @@
 - When testing hot orchestration streams backed by PubSub, avoid `fork + sleep` subscription races. Start the collector with an explicit readiness handshake (for example `Effect.forkScoped` plus `Effect.yieldNow`, or another deterministic subscription barrier) before dispatching commands.
 - Keep interactive controls properly disabled during in-flight async operations (e.g. export, share, revoke): users must not be able to trigger conflicting actions while a prior action is still completing. Guard format toggles, download buttons, and secondary actions behind the relevant `isSaving`/`isRevoking` flags.
 - Keep sidebar organization logic centralized. Pin/archive/search/filter/sort behavior should stay in shared helpers/stores (`apps/web/src/components/Sidebar.logic.ts`, `apps/web/src/lib/threadOrdering.ts`, `apps/web/src/sidebarPreferencesStore.ts`) instead of being reimplemented ad hoc inside multiple sidebar render branches.
+- Keep project-creation and first-run onboarding flows centralized through the shared project-creation hook/component path. Empty-state onboarding and the sidebar add-project affordance should reuse the same project-create + first-thread navigation logic instead of drifting into separate implementations.
+- Normalize workspace-path comparisons in the shared project-creation flow before deciding whether a project already exists. Trailing slashes, slash-direction differences, and Windows drive-letter casing should not create duplicate projects or break the “focus existing project” path.
+- Do not swallow first-thread navigation failures after creating a project. If project creation succeeds but opening the initial draft fails, surface that error so the UI does not pretend setup finished cleanly.
+- Keep new-thread draft-context normalization centralized. When reusing an existing draft in `Local` mode, explicitly clear inherited branch/worktree state instead of silently reopening a stale worktree-backed draft.
 - Keep chat follow-up queue state centralized in `apps/web/src/threadSendQueue.ts` instead of duplicating per-thread queue bookkeeping inside individual composer controls.
 - Keep ARIA semantics aligned with visual affordances: disclosure/expand buttons need `aria-expanded`, toggle-style buttons need `aria-pressed` or `role="radio"` with `aria-checked`, icon-only buttons need explicit `aria-label`, tree-like file lists need `role="tree"`, and controls revealed only on hover (e.g. terminal close buttons) must also be revealed on `focus-visible` so keyboard users can reach them.
 - Keep `aria-label` values on interactive groups and their trigger buttons accurate and descriptive of the actual feature. Do not leave placeholder labels from copy-paste (e.g. "Subscription actions" for an editor picker, "Copy options" for an editor menu).

README.md

@@ -49,7 +49,7 @@ If this fork does not currently publish desktop releases, build one locally with
 
 Published CUT3 builds are listed on the [CUT3 Releases page](https://github.com/yappologistic/t3code/releases).
 
-Once the app is running, choose Codex, GitHub Copilot, OpenCode, Kimi Code, or Pi from the provider picker before starting a session.
+Once the app is running, choose Codex, GitHub Copilot, OpenCode, Kimi Code, or Pi from the provider picker before starting a session. If this is your first run and CUT3 does not know any projects yet, the empty chat view now walks you through adding a project folder and immediately opens the first draft thread for it.
 
 ## Workspace instructions and slash commands
 
@@ -108,13 +108,14 @@ Open Settings in the app to configure provider-specific behavior on the current
 - **Appearance**: choose the base light/dark/system mode, switch to integrated presets like Lilac, and configure a custom chat background image with adjustable fade and blur.
 - **Language**: switch the settings experience and shared app shell between English and Persian. Persian also flips document direction and locale-aware time/date formatting in the web UI.
 - **Provider overrides**: set custom binary paths for Codex, Copilot, OpenCode, or Kimi, plus an optional Codex home path, a shared OpenRouter API key, and a Kimi API key. Pi is embedded through CUT3's Node dependency instead of a separate binary override; CUT3 reads Pi auth/models config from `~/.pi/agent`, keeps Pi packages, AGENTS files, system prompts, extensions, skills, prompt templates, and themes disabled so workspace instructions still come only from CUT3, and now surfaces authenticated Pi provider/model ids directly in the picker and `/model` suggestions instead of only showing a static `pi/default` placeholder. OpenCode account authentication still happens outside CUT3 through `opencode auth login` and `opencode auth logout`, while MCP server auth/debug remains server-specific through commands like `opencode mcp auth <server>` and `opencode mcp debug <server>`. The OpenCode settings panel inspects the resolved OpenCode config paths plus `opencode auth list`, `opencode mcp list`, and `opencode mcp auth list` so CUT3 can show current credentials, provider-specific MCP status (including disabled and auth-gated entries), and copyable recovery commands. Kimi CLI authentication can use either `kimi login` or the in-shell `/login` flow when you are not using an API key, and new OpenCode sessions now inherit that shared OpenRouter key as `OPENROUTER_API_KEY` when the OpenCode provider config expects it.
-- **OpenRouter free models**: review the current OpenRouter entries that are explicitly free-locked and compatible with CUT3's native tool-calling path (`tools` plus `tool_choice`), keep the built-in `openrouter/free` router handy, and pin any listed model into the picker.
+- **OpenRouter free models**: review the current OpenRouter entries that are explicitly free-locked and compatible with CUT3's native tool-calling path (`tools` plus `tool_choice`), keep the built-in `openrouter/free` router handy, and pin any listed model into the picker. CUT3 now keeps a last-known-good OpenRouter free-model catalog locally so the picker and settings can stay usable even when the next live catalog refresh fails.
 - **Custom model slugs**: save extra model ids for GitHub Copilot, OpenCode, Kimi, Pi provider/model ids such as `github-copilot/claude-sonnet-4.5`, custom Codex models, or current OpenRouter `:free` slugs so they appear in the model picker and `/model` suggestions.
-- **Picker controls**: the chat composer now uses a searchable grouped model picker with direct `Connect provider` and `Manage models` actions.
-- **Model visibility**: hide or restore discovered and saved models without deleting them; hidden models are removed from both the picker and `/model` suggestions until you show them again.
+- **Picker controls**: the chat composer now uses a searchable grouped model picker with direct `Usage`, `Provider readiness`, and `Manage models` actions.
+- **Favorites, recents, and visibility**: pin favorite models so they stay at the top of the picker, let CUT3 surface recent model choices ahead of the long tail, and hide or restore discovered/saved models without deleting them. Hidden models are removed from both the picker and `/model` suggestions until you show them again.
 - **Thread defaults**: choose whether new draft threads start in `Local` or `New worktree`, and set thread sharing to `Manual`, `Auto` (create a share link after a new server-backed thread settles), or `Disabled` for new links.
 - **Codex service tier**: choose `Automatic`, `Fast`, or `Flex` as the default service tier for new Codex turns.
 - **Per-turn controls**: the composer exposes provider-aware reasoning controls where CUT3 has a provider-specific contract today. Codex and GitHub Copilot expose provider-specific reasoning levels, Codex also supports a per-turn `Fast Mode` toggle, and Pi now surfaces its live model reasoning capability plus Pi thinking levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`) for reasoning-capable Pi models while still preserving Pi defaults until you choose an override.
+- **Usage dashboard**: click the composer context ring or the picker `Usage` action to open a unified usage dashboard for the current selection, including documented/live context limits, token breakdowns from the latest matching runtime snapshot, latest reported spend when the provider exposes it, and GitHub Copilot quota details.
 - **Response visibility**: choose whether assistant messages stream token-by-token and whether tool/work-log entries stay visible in the main timeline.
 - **Permission policies**: save persistent app-wide or project-scoped approval rules with `allow`, `ask`, or `deny` actions, request-kind filters, request-type/detail matching, and Build/Plan/Review presets.