diff --git a/.gitignore b/.gitignore
index b0dd8bb..5d974dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,8 @@ node_modules/
 # Internal development files
 internal/
 docs/superpowers/
+agents.md
+.agents/
 
 # Logs
 *.log
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0c2f2b..a8e303d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,32 @@ All notable changes to the Cloudinary VS Code extension will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-06-30
+
+### Added
+- **Docs AI assistant** - In-editor chat with Cloudinary documentation. Includes chat history, source citations, and a dedicated webview panel.
+- **Homescreen sidebar** - Redesigned home view with search, environment switcher, recent conversations, and an AI tools panel.
+- **Configure AI Tools** - One-click installer for Cloudinary skills and MCP servers across Cursor, GitHub Copilot, Windsurf, Claude Code, and Universal targets. Scope-aware (global vs. workspace) with install-status detection.
+- **Webview-based asset explorer** - Replaces the native VS Code tree view. Supports streaming pagination, search, and parallel fetching.
+- **Analytics tracking** - Anonymous usage telemetry for commands and webview interactions. Sensitive payload keys are stripped before transmission; session id persisted in global state.
+- **CI: VSIX build artifacts** - Feature branches now produce installable VSIX builds with PR-comment download links.
+
+### Changed
+- **Welcome screen interactions** - Refreshed onboarding flow.
+- **Cloudinary webview toolbar** - Unified toolbar styling across Docs AI, library, and homescreen.
+- **Homescreen renders shell instantly** - Static shell paints first, data loads asynchronously.
+- **AI tools platform detection** - Auto-detects installed AI platforms (Cursor, Copilot, etc.) on panel open; defaults to GitHub Copilot when running inside VS Code.
+
+### Fixed
+- Preview and upload panels close on environment switch instead of attempting in-place update.
+- Home recent-conversations list refreshes correctly after new chats.
+- Upload panel title shows the active cloud name; presets refetched on environment switch.
+- Docs AI prompt handoff no longer flashes during transition.
+
+## [0.1.5]
+
+Skipped — released as part of 1.0.0.
+
 ## [0.1.4] - 2026-04-16
 
 ### Added
@@ -70,7 +96,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Asset refresh functionality
 - Support for both fixed and dynamic folder modes
 - Configurable upload presets
-- Beta version with ongoing feature development
+- General availability release baseline
 
 ### Technical
 - Built with TypeScript
diff --git a/README.md b/README.md
index 5f1ed41..f61343a 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,14 @@
-# Cloudinary VS Code Extension (Beta)
+# Cloudinary VS Code Extension
 
 Easily explore, search, preview, and upload Cloudinary assets directly inside Visual Studio Code or supported IDE.
 
-**Note**: This is a beta version of the extension. Some features are subject to change. Please report any problems or feedback by opening an issue.
+**General availability release**: Please report any problems or feedback by opening an issue.
 
 ---
 
 ## Features
 
-- **Asset Explorer** – View Cloudinary folders and assets in a VS Code Tree View
+- **Asset Explorer** – View Cloudinary folders and assets in the sidebar media library
 - **Search & Filter** – Quickly locate assets by public ID or type
 - **Optimized Preview** – Preview images/videos with Cloudinary transformations applied (`f_auto`, `q_auto`)
 - **Right-click Actions** – Copy Public ID or URL instantly
@@ -75,7 +75,7 @@ Once a valid configuration has been added, the active environment will be shown
 
 ### Upload
 
-- Click **Upload** from the title bar to open the upload panel, or click **Upload here** on a folder entry to open with that folder pre-selected.
+- Click **Upload** from the library toolbar to open the upload panel, or click **Upload here** on a folder entry to open with that folder pre-selected.
 - Alternatively, run `Cloudinary: Upload` from the command palette.
 
 **Upload Panel Features:**
@@ -94,8 +94,8 @@ Once a valid configuration has been added, the active environment will be shown
 ![Uploading assets](https://res.cloudinary.com/demo/video/upload/w_1200/f_auto:animated/q_auto/e_accelerate:100/e_loop/docs/vscode-extension-vid3)
 
 ### Filter or Search
-- Click "Filter" in the title bar or run `Cloudinary: Filter` to narrow assets by type
-- Click "Search" in the title bar or run `Cloudinary: Search` to search by public ID
+- Use the always-visible filter controls in the media library to narrow assets by type or change sort order.
+- Use the always-visible search field in the media library to search by public ID.
 
 ![Filtering and searching](https://res.cloudinary.com/demo/video/upload/w_1200/f_auto:animated/q_auto/e_accelerate:50/e_loop/docs/vscode-extension-vid2)
 
@@ -113,16 +113,17 @@ Once a valid configuration has been added, the active environment will be shown
 - **Metadata** – View tags, context metadata, and structured metadata
 - **URLs** – Copy original or optimized URLs with one click
 - **Type Icons** – Tab icons indicate asset type (image, video, or file)
+- **Authenticated Assets** – Authenticated delivery assets are marked with a lock and use a signed original URL for preview/copy actions
 
-### Refresh Tree
-- Click "Refresh" to reload the tree
+### Refresh Library
+- Click **Refresh** to reload the media library
 
 ---
 
 ## Known Limitations
 - Asset filtering is limited to basic types (image, video, raw)
-- No options to control number of items returned in tree or root folder
-- Folder dropdown in upload panel only shows folders that have been browsed in the tree view
+- No user-facing option to control library page size or prefetch cap
+- Folder dropdown discovery is capped to a bounded folder depth for responsiveness
 
 ---
 
diff --git a/RELEASE_v1.0.0.md b/RELEASE_v1.0.0.md
new file mode 100644
index 0000000..04c6d36
--- /dev/null
+++ b/RELEASE_v1.0.0.md
@@ -0,0 +1,37 @@
+# Cloudinary VS Code Extension — v1.0.0
+
+> General availability release.
+
+## What's new
+
+### Added
+
+- **Docs AI assistant** — In-editor chat with Cloudinary documentation. Includes chat history, source citations, and a dedicated webview panel.
+- **Homescreen sidebar** — Redesigned home view with search, environment switcher, recent conversations, and an AI tools panel.
+- **Configure AI Tools** — One-click installer for Cloudinary skills and MCP servers across Cursor, GitHub Copilot, Windsurf, Claude Code, and Universal targets. Scope-aware (global vs. workspace) with install-status detection.
+- **Webview-based asset explorer** — Replaces the native VS Code tree view. Supports streaming pagination, search, and parallel fetching.
+- **Analytics tracking** — Anonymous usage telemetry for commands and webview interactions. Sensitive payload keys are stripped before transmission; session id persisted in global state.
+- **CI: VSIX build artifacts** — Feature branches now produce installable VSIX builds with PR-comment download links.
+
+### Changed
+
+- **Welcome screen interactions** — Refreshed onboarding flow.
+- **Cloudinary webview toolbar** — Unified toolbar styling across Docs AI, library, and homescreen.
+- **Homescreen renders shell instantly** — Static shell paints first, data loads asynchronously.
+- **AI tools platform detection** — Auto-detects installed AI platforms (Cursor, Copilot, etc.) on panel open; defaults to GitHub Copilot when running inside VS Code.
+
+### Fixed
+
+- Preview and upload panels close on environment switch instead of attempting in-place update.
+- Home recent-conversations list refreshes correctly after new chats.
+- Upload panel title shows the active cloud name; presets refetched on environment switch.
+- Docs AI prompt handoff no longer flashes during transition.
+
+## Install
+
+1. Save the `cloudinary-1.0.0.vsix` file somewhere on your machine.
+2. In VS Code: `Cmd+Shift+P` → **Extensions: Install from VSIX…** → pick the file.
+   Or from a terminal: `code --install-extension cloudinary-1.0.0.vsix --force`
+3. Reload the window: `Cmd+Shift+P` → **Developer: Reload Window**.
+
+The Cloudinary icon should appear in the Activity Bar.
diff --git a/TESTING_GUIDE_v1.0.0.md b/TESTING_GUIDE_v1.0.0.md
new file mode 100644
index 0000000..722cac7
--- /dev/null
+++ b/TESTING_GUIDE_v1.0.0.md
@@ -0,0 +1,183 @@
+# Testing guide: Cloudinary VS Code extension v1.0.0
+
+Hey team, this build is for the v1.0.0 GA release of the VS Code extension. Below is what's new and what to poke at.
+
+> 💬 **Feedback:** Please share your feedback about the extension in the shared Google Doc. Bugs welcome, copy nits welcome, "this UX is confusing" welcome.
+> For comments about the AI responses, please use the thumbs up/down feature on each message to leave feedback tied to conversations.
+
+---
+
+## 1. Install
+
+1. Save `cloudinary-1.0.0.vsix` somewhere on your Mac.
+2. In VS Code:
+   - `Cmd+Shift+P` → **Extensions: Install from VSIX…** → pick the file
+   - **or** open your extensions pane, then drag and drop the VSIX file into it
+3. Reload: `Cmd+Shift+P` → **Developer: Reload Window**.
+4. Open the **Cloudinary icon** in the Activity Bar
+
+### If you've never set up Cloudinary credentials before
+
+You should see a "Add your API credentials to connect" banner on the homescreen. Click **Configure** to open the global config file. Paste your cloud name + API key + API secret. Save the file. The banner should disappear and your cloud name should appear at the top.
+
+If you already have credentials configured, skip ahead.
+
+---
+
+## 2. Smoke test: does anything obviously break?
+
+- [ ] The Cloudinary icon shows in the Activity Bar.
+- [ ] Clicking it opens the homescreen with no errors.
+- [ ] Your cloud name appears at the top of the homescreen.
+- [ ] The "Browse Library", "Upload", and "Configure AI Tools" tiles all render.
+- [ ] The "Ask Cloudinary AI" section (heading + textarea + suggested-question chips) renders below the tiles.
+- [ ] No red error notifications pop up.
+
+If any of these fail, stop and report. The rest of the guide assumes the basics work.
+
+---
+
+## 3. Homescreen
+
+The homescreen is the new landing view. Test:
+
+- [ ] **Search box**: type a query (e.g. `transformation`). Hitting Enter should open the library view with that search applied.
+- [ ] **Status pill (top right)**: the text reads "Connected" when your credentials are valid, "Setup needed" otherwise. There's a small dot beside the text that changes appearance when not configured.
+- [ ] **Folder mode chip**: shows "Dynamic folders" or "Fixed folders" beside your cloud name (only when credentials are configured).
+- [ ] **Browse Library tile**: clicking opens the library view.
+- [ ] **Upload tile**: clicking opens the upload widget panel.
+- [ ] **Switch Environment tile**: only appears if you have 2+ environments configured. Clicking it should let you swap.
+- [ ] **Configure AI Tools tile**: clicking expands an inline panel below the tile (see Section 6). Clicking again collapses it.
+- [ ] **Ask Cloudinary AI section**: heading "Ask Cloudinary AI", subtitle, a "Send a message…" textarea, a send button, and 4 suggested-question chips ("What's new in Cloudinary?", "How do I upload images?", "Explain image transformations", "What SDKs does Cloudinary support?"). Pressing Enter or clicking send takes you into Docs AI with that prompt pre-filled.
+- [ ] **View recent conversations**: a clock-icon toggle appears below the Ask Cloudinary AI section once you have one or more past chats. Clicking it expands a list of recent conversations.
+- [ ] **Welcome Guide** link in the footer.
+
+**Things to look for:**
+- Does the homescreen render quickly? It's supposed to paint a static shell first and load data after.
+- Any visual jank when you resize the sidebar narrow vs. wide?
+- Anything that feels off in the copy?
+
+---
+
+## 4. Library view
+
+Open the library by clicking the "Browse Library" tile on the homescreen. This swaps the Cloudinary sidebar from the homescreen over to the library view. To get back, click the Home button in the toolbar at the top of the library view.
+
+- [ ] **Folder expand**: clicking a folder reveals its contents. Big folders should stream in (a loading row appears at the bottom).
+- [ ] **Search**: the search input at the top filters across the library. Pressing Escape clears it.
+- [ ] **Type filter**: dropdown with All / Images / Videos / Raw.
+- [ ] **Sort**: dropdown with Newest / Oldest.
+- [ ] **Click an asset**: opens a preview panel with optimized image/video, public ID, copy buttons, and metadata.
+- [ ] **Right-click an asset**: context menu with options to copy the public ID, the URL, and the optimized URL.
+- [ ] **Switch environment while a preview is open**: the preview panel closes cleanly (rather than trying to update in place with stale data).
+
+**Things to look for:**
+- Does scrolling stay smooth with hundreds of items?
+- Does the loading indicator behave correctly at the bottom?
+- Are folder icons and asset thumbnails rendering properly?
+
+---
+
+## 5. Docs AI chat: biggest new feature
+
+This is the in-editor doc chatbot. The Cloudinary sidebar shows one view at a time (Homescreen, Library, or Docs AI), so opening Docs AI swaps the sidebar over to that view. Ways to get there:
+
+- Type in the "Ask Cloudinary AI" textarea on the homescreen and submit (sends your prompt and opens Docs AI).
+- Click any of the suggested-question chips on the homescreen.
+- Click a recent conversation entry on the homescreen (after you have any).
+- Run "Open Docs AI" from the Command Palette.
+
+To return to the homescreen, click the Home button in the toolbar at the top of the Docs AI view.
+
+The Docs AI view contains: a tab strip at the top (one tab per conversation), a "+" button to start a new chat, a clock-icon button for chat history, a conversation area, and a composer at the bottom with a textarea (placeholder "Send a message…"), a send button, and a stop button.
+
+- [ ] **Ask a basic question** (e.g. "How do I upload an image with Node.js?"). The response should stream in word by word.
+- [ ] **Inline citations**: numbered citation markers appear in the answer text and link to the corresponding sources.
+- [ ] **Sources section**: a collapsible "Sources" block sits below the answer with a chevron toggle. Clicking a source link opens the docs page in your browser.
+- [ ] **Follow-up questions**: 2-3 suggested follow-up prompts appear below an answer.
+- [ ] **Disclaimer line** at the bottom: "AI can make mistakes. Verify important info from Cloudinary docs."
+
+### Chat history
+
+- [ ] **New chat (+ button)**: starts a fresh conversation in a new tab.
+- [ ] **Tab strip**: each conversation gets its own tab at the top. You can switch between them.
+- [ ] **History button (clock icon)**: opens a dropdown of past conversations.
+- [ ] **Clear all conversations**: from the history dropdown, there should be a way to delete all. Confirm there's a "Delete all conversations?" confirmation before it deletes.
+
+### Things to test for content quality
+
+- [ ] **Recent docs are in the index**: try asking about something that landed in the May 2026 MediaFlows release notes (e.g. "What's the Workflow Agent in MediaFlows?"). It should answer correctly.
+- [ ] **Stop generation**: start a long answer, hit the stop button mid-stream. The stream should stop cleanly.
+- [ ] **Non-English question**: try Hebrew, Spanish, or another language. The bot should answer in that language.
+- [ ] **Code in answers**: questions about code should get back fenced code blocks that look right.
+- [ ] **Thumbs up/down on each AI message**: confirm both states register (the bot acknowledges the feedback was saved).
+
+**Known limitation:** docs marked `noindex: true` are intentionally excluded from the chatbot index (e.g. internal-only pages or Beta features still in alpha). So if you ask about a hidden/beta-only feature, it might not have it.
+
+---
+
+## 6. Configure AI Tools
+
+This installs Cloudinary skills + MCP servers into your AI coding tools (Cursor, Claude Code, VS Code Copilot, Windsurf, and many more).
+
+- [ ] Click the **Configure AI Tools** tile on the homescreen. An inline panel expands below it.
+- [ ] **Platform dropdown**: pick from the list of supported platforms. The dropdown should default to one that matches your current environment when possible (e.g. "VS Code (Copilot)" when running inside VS Code).
+- [ ] **Scope toggle**: two buttons, "Project" and "Global". Toggle between them.
+- [ ] **Skills + MCP servers list**: shows checkboxes for each available skill and MCP server. Items already installed for the chosen platform + scope are shown as disabled / pre-checked.
+- [ ] **Apply button**: enabled only when you have at least one selection to install. Click it. The button label changes to "Applying…", then each item shows a ✓ (success) or ✕ (failure) tick.
+- [ ] **Reopen the panel**: skills you installed should now show as already installed (not re-offering them at the same scope).
+- [ ] **Switch platform** mid-flow: changing the platform dropdown should reload the list with whatever is correct for that new platform.
+
+**Things to look for:**
+- Does the platform list cover what you actually use?
+- Did it auto-pick the right default platform for you?
+- Are the install instructions / cover notes clear?
+- Anything that errors silently or fails without a clear message?
+
+---
+
+## 7. Upload widget
+
+- [ ] Click "Upload" on the homescreen. The upload widget panel opens.
+- [ ] Drag a file onto it (or pick one via the file picker). Progress should show in real time.
+- [ ] Upload completes, the asset appears in the recently-uploaded section.
+- [ ] **Chunked upload**: try a file larger than 20 MB (the threshold for chunked uploads). It should complete reliably without timing out.
+- [ ] **Switch environment with the widget open**: the widget should close cleanly rather than try to update in place.
+- [ ] The panel title should reflect the active cloud name.
+
+---
+
+## 8. Environment switching
+
+Only relevant if you have multiple Cloudinary environments configured.
+
+- [ ] The VS Code **status bar at the bottom** shows a cloud icon followed by the active cloud name.
+- [ ] Click the status bar item (or use the Switch Environment tile on the homescreen) to swap environments.
+- [ ] After switching:
+  - Library view refreshes with the new environment's assets.
+  - Upload presets refetch.
+  - Any open preview/upload panels close cleanly.
+  - The folder-mode chip updates if the new environment uses a different mode.
+
+---
+
+## Known limitations / things NOT in this build
+
+- The "**Docs AI agent actions**" feature (the experimental version where the bot can take actions on your media library directly) is **not** in this build. That's still on a feature branch.
+- No marketplace publishing yet. This is a side-load VSIX only.
+- KB articles flagged `noindex: true` in our docs source are intentionally excluded from the Docs AI index.
+
+---
+
+## What we'd love to know
+
+1. **First-impression UX**: what feels off when you first open the extension?
+2. **Docs AI answer quality**: does it actually help you find what you'd normally search for in our docs?
+3. **Performance**: any slow spots? Sidebar lag, library scroll jank, Docs AI streaming delays?
+4. **Copy**: anything in button labels, tooltips, or empty states that doesn't quite read right?
+5. **Platform detection** in Configure AI Tools: did it correctly identify what you have installed?
+6. **Anything that crashed or showed an error**: please screenshot + the steps to reproduce.
+
+Drop notes in the shared Google Doc, or reply on the email thread.
+
+Thanks for testing! 🙏
diff --git a/docs/adding-features.md b/docs/adding-features.md
index 5439ff0..69f0200 100644
--- a/docs/adding-features.md
+++ b/docs/adding-features.md
@@ -1,26 +1,32 @@
 # Adding Features
 
-This guide explains how to add new functionality to the Cloudinary VS Code Extension.
+This guide covers the current extension shape after the sidebar moved to webview-based homescreen and library views.
 
 ## Adding a New Command
 
-### 1. Create the Command File
+Commands still live in `src/commands/`, but they now work from shared services and webview providers rather than a sidebar tree state object.
 
-Create a new file in `src/commands/`:
+### 1. Create the Command File
 
 ```typescript
 // src/commands/myNewCommand.ts
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { CloudinaryService } from "../cloudinary/cloudinaryService";
 
 function registerMyNewCommand(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryService: CloudinaryService
 ) {
   context.subscriptions.push(
     vscode.commands.registerCommand("cloudinary.myNewCommand", async () => {
-      // Implementation here
-      vscode.window.showInformationMessage("Command executed!");
+      if (!cloudinaryService.cloudName) {
+        vscode.window.showWarningMessage("Cloudinary is not configured.");
+        return;
+      }
+
+      vscode.window.showInformationMessage(
+        `Running against ${cloudinaryService.cloudName}`
+      );
     })
   );
 }
@@ -28,23 +34,29 @@ function registerMyNewCommand(
 export default registerMyNewCommand;
 ```
 
+If the command needs to update the library UI, accept `LibraryWebviewViewProvider` and call methods such as `refresh()`, `setSearch()`, or `applyView(...)`.
+
 ### 2. Register the Command
 
-Add to `src/commands/registerCommands.ts`:
+Add it in `src/commands/registerCommands.ts`:
 
 ```typescript
 import registerMyNewCommand from "./myNewCommand";
 
 function registerAllCommands(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryService: CloudinaryService,
+  environmentTarget: Parameters<typeof registerSwitchEnv>[1],
+  statusBar: vscode.StatusBarItem,
+  homescreenProvider: HomescreenViewProvider,
+  libraryWebview?: LibraryWebviewViewProvider
 ) {
-  // ... existing registrations
-  registerMyNewCommand(context, provider);
+  // ...existing registrations
+  registerMyNewCommand(context, cloudinaryService);
 }
 ```
 
-### 3. Add to Package.json
+### 3. Add It to `package.json`
 
 ```json
 {
@@ -53,311 +65,155 @@ function registerAllCommands(
       {
         "command": "cloudinary.myNewCommand",
         "title": "My New Command",
-        "category": "Cloudinary",
-        "icon": "$(symbol-misc)"
+        "category": "Cloudinary"
       }
     ]
   }
 }
 ```
 
-### 4. Add Menu Placement (Optional)
+The library toolbar and context actions are rendered inside the webview, so most new UI affordances do not need `contributes.menus`.
 
-```json
-{
-  "contributes": {
-    "menus": {
-      "view/title": [
-        {
-          "command": "cloudinary.myNewCommand",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation"
-        }
-      ],
-      "view/item/context": [
-        {
-          "command": "cloudinary.myNewCommand",
-          "when": "viewItem == asset",
-          "group": "inline"
-        }
-      ]
-    }
-  }
-}
-```
+## Extending the Library Webview
 
-## Adding a New Tree Item Type
+The media library is implemented by `src/webview/libraryView.ts` plus the client bundle in `src/webview/client/library.ts`.
 
-### 1. Add the Type
+### Host-side changes
 
-In `src/tree/cloudinaryItem.ts`:
+Use `LibraryWebviewViewProvider` when you need to:
 
-```typescript
-export type CloudinaryItemType = 
-  | 'asset' 
-  | 'folder' 
-  | 'loadMore' 
-  | 'myNewType';  // Add your type
-```
+- send new data into the webview
+- respond to `postMessage(...)` events from the client
+- persist small UI preferences in `context.globalState`
 
-### 2. Handle in Constructor
+Host messages are handled in `handleMessage(...)`. Outbound posts use the private `post(...)` helper, which wraps `webview.postMessage(...)` in a try/catch so late callbacks (prefetches, env-change broadcasts) do not throw `Webview is disposed` after a view collapses. Add new helpers via the same wrapper rather than calling `webview.postMessage` directly.
 
-```typescript
-else if (type === 'myNewType') {
-  this.contextValue = 'myNewType';
-  this.iconPath = new vscode.ThemeIcon('symbol-misc');
-  this.tooltip = 'My new item type';
-  this.command = {
-    command: 'cloudinary.handleMyNewType',
-    title: 'Handle',
-    arguments: [data],
-  };
-}
-```
+When something on the host changes that the client should reflect immediately (env switch, refresh), prefer the existing routes — `envChanged()`, `refresh()`, `setSearch()`, `applyView(...)` — instead of posting raw messages.
 
-### 3. Create Items in Provider
+### Client-side changes
 
-In `src/tree/treeDataProvider.ts`:
+Add interactive behavior in `src/webview/client/`:
 
-```typescript
-const myItem = new CloudinaryItem(
-  'Item Label',
-  vscode.TreeItemCollapsibleState.None,
-  'myNewType',
-  { customData: 'value' },
-  this.cloudName!,
-  this.dynamicFolders
-);
-items.push(myItem);
-```
+- `library.ts` — main row rendering, selection, keyboard nav, message dispatch
+- `libraryVirtualList.ts` — windowed render math (row height fixed at 22px)
+- `libraryRowSplice.ts` — depth-aware splice helper for streaming nested folder appends
+- `libraryIcons.ts` — duplicated SVG icon set used at row-render time (the client cannot import `src/webview/icons.ts`; keep these two in sync when adding a glyph used in both surfaces)
+- `libraryMenu.ts` — context menu
+- `libraryHoverPreview.ts` — delayed thumbnail hover card with metadata strip
 
-### 4. Add Context Menu (Optional)
+These files are bundled by `esbuild.js` into `media/scripts/`.
 
-```json
-{
-  "contributes": {
-    "menus": {
-      "view/item/context": [
-        {
-          "command": "cloudinary.myCommand",
-          "when": "viewItem == myNewType"
-        }
-      ]
-    }
-  }
-}
-```
+### Library UI conventions
 
-## Adding a New Webview
+- **Row height** is fixed at 22px (`--lib-row-height`). Do not introduce variable row heights — virtualization assumes a constant.
+- **Icon slots** are 18×22 flexbox-centered. New row kinds should follow the same pattern: `<indent><twistie><icon><name>` so vertical alignment matches existing rows.
+- **Brand accents** come from `tokens.css` — use `--lib-accent` (sky blue) and the `--lib-accent-soft/-strong` derivatives. Avoid hardcoded colors.
+- **Toolbar groups** are HTML siblings with `gap` for spacing instead of vertical hairline dividers; the utility group uses `margin-left: auto` to push to the right edge.
+- **Search and filters** stay visible in the library header. Do not add toolbar toggles for core browse controls unless the layout changes again.
 
-### 1. Create the Command File
+## Adding a New Webview Panel or View
+
+Use the shared webview helpers in `src/webview/webviewUtils.ts`:
 
 ```typescript
-// src/commands/myWebview.ts
 import * as vscode from "vscode";
-import { createWebviewDocument, getScriptUri } from "../webview/webviewUtils";
-import { escapeHtml } from "../webview/utils/helpers";
-
-let panel: vscode.WebviewPanel | undefined;
-
-function registerMyWebview(context: vscode.ExtensionContext) {
-  context.subscriptions.push(
-    vscode.commands.registerCommand("cloudinary.openMyWebview", () => {
-      if (panel) {
-        panel.reveal();
-        return;
-      }
-
-      panel = vscode.window.createWebviewPanel(
-        "cloudinaryMyWebview",
-        "My Webview",
-        vscode.ViewColumn.One,
-        {
-          enableScripts: true,
-          localResourceRoots: [
-            vscode.Uri.joinPath(context.extensionUri, "src", "webview", "media"),
-          ],
-        }
-      );
-
-      panel.webview.html = createWebviewDocument({
-        title: "My Webview",
-        webview: panel.webview,
-        extensionUri: context.extensionUri,
-        bodyContent: getContent(),
-        inlineScript: "initCommon();",
-      });
-
-      panel.webview.onDidReceiveMessage((message) => {
-        switch (message.command) {
-          case "doSomething":
-            // Handle message
-            break;
-        }
-      });
-
-      panel.onDidDispose(() => {
-        panel = undefined;
-      });
-    })
+import {
+  createWebviewDocument,
+  getScriptUri,
+  getStyleUri,
+} from "../webview/webviewUtils";
+
+function openMyPanel(context: vscode.ExtensionContext) {
+  const panel = vscode.window.createWebviewPanel(
+    "cloudinaryMyPanel",
+    "My Panel",
+    vscode.ViewColumn.One,
+    {
+      enableScripts: true,
+      localResourceRoots: [vscode.Uri.joinPath(context.extensionUri, "media")],
+    }
   );
-}
 
-function getContent(): string {
-  return `
-    <div class="container">
-      <div class="card card--elevated">
-        <div class="card__body">
-          <h2>My Webview</h2>
-          <p>Content here</p>
-          <button class="btn btn--primary" id="myButton">Click Me</button>
-        </div>
-      </div>
-    </div>
-  `;
+  const scriptUri = getScriptUri(panel.webview, context.extensionUri, "my-panel.js");
+  const styleUri = getStyleUri(panel.webview, context.extensionUri, "my-panel.css");
+
+  panel.webview.html = createWebviewDocument({
+    title: "My Panel",
+    webview: panel.webview,
+    extensionUri: context.extensionUri,
+    bodyContent: `<div id="root"></div>`,
+    additionalStyles: [styleUri],
+    additionalScripts: [scriptUri],
+  });
 }
-
-export default registerMyWebview;
-```
-
-### 2. Add Custom JavaScript (Optional)
-
-Create `src/webview/media/scripts/my-webview.js`:
-
-```javascript
-/**
- * My Webview functionality.
- */
-
-function initMyWebview() {
-  const button = document.getElementById('myButton');
-  if (button) {
-    button.addEventListener('click', () => {
-      vscode.postMessage({ command: 'doSomething' });
-    });
-  }
-}
-```
-
-Update the webview to include it:
-
-```typescript
-const myScriptUri = getScriptUri(panel.webview, context.extensionUri, "my-webview.js");
-
-panel.webview.html = createWebviewDocument({
-  // ...
-  additionalScripts: [myScriptUri],
-  inlineScript: "initCommon(); initMyWebview();",
-});
 ```
 
-### 3. Register and Add to Package.json
-
-Same as adding a command (see above).
+Keep styling on VS Code theme tokens such as `--vscode-editor-foreground`.
 
 ## Adding Configuration Options
 
-### 1. Update Configuration Interface
+Configuration still comes from Cloudinary environment files, not VS Code settings.
 
-In `src/config/configUtils.ts`:
+### 1. Update the Config Type
 
-```typescript
-export interface CloudinaryEnvironment {
-  apiKey: string;
-  apiSecret: string;
-  uploadPreset?: string;
-  myNewOption?: string;  // Add your option
-}
-```
+Add the field to `CloudinaryEnvironment` in `src/config/configUtils.ts`.
 
-### 2. Use in Code
+### 2. Thread It Through Activation
 
-```typescript
-const myOption = provider.getConfig().myNewOption || 'default';
-```
+If the option affects runtime behavior, read it during activation or environment switching and write it onto `CloudinaryService` or the specific provider/panel that needs it.
 
-### 3. Document the Option
+### 3. Document It
 
-Update `docs/configuration.md` with the new option.
+Update the relevant docs in `docs/`.
 
 ## Common Patterns
 
 ### Error Handling
 
 ```typescript
-import { handleCloudinaryError } from '../utils/cloudinaryErrorHandler';
+import { handleCloudinaryError } from "../utils/cloudinaryErrorHandler";
 
 try {
-  const result = await cloudinary.api.someMethod();
+  await cloudinaryService.fetchChildren("");
 } catch (err: any) {
-  handleCloudinaryError('Operation failed', err);
+  handleCloudinaryError("Failed to load assets", err);
 }
 ```
 
 ### User Input
 
 ```typescript
-// Input box
 const query = await vscode.window.showInputBox({
-  placeHolder: 'Enter search term',
-  prompt: 'Search assets by public ID',
-  validateInput: (value) => value ? null : 'Cannot be empty'
+  placeHolder: "Enter search term",
+  prompt: "Search assets by public ID",
 });
 
-if (!query) return;  // User cancelled
-
-// Quick pick
-const selected = await vscode.window.showQuickPick(
-  ['Option 1', 'Option 2', 'Option 3'],
-  { placeHolder: 'Select an option' }
-);
+if (!query) {
+  return;
+}
 ```
 
-### Progress Indicator
+### Refreshing the Sidebar
 
 ```typescript
-await vscode.window.withProgress(
-  {
-    location: vscode.ProgressLocation.Notification,
-    title: 'Loading assets...',
-    cancellable: false,
-  },
-  async (progress) => {
-    progress.report({ increment: 0 });
-    // Do work
-    progress.report({ increment: 50 });
-    // More work
-    progress.report({ increment: 100 });
-  }
-);
+await libraryWebview?.refresh();
+await homescreenProvider.refresh();
 ```
 
-### Refresh Tree View
-
-```typescript
-// After modifying data
-provider.refresh();  // Fires _onDidChangeTreeData
-```
+Use the narrowest refresh path you need. Do not recreate deprecated tree-provider refresh flows.
 
 ## Testing Your Changes
 
-1. **Compile**: `npm run compile`
-2. **Launch**: Press `F5` to open Extension Development Host
-3. **Test**: Verify functionality works as expected
-4. **Reload**: Press `Ctrl+R` / `Cmd+R` after code changes
-
-### Manual Testing Checklist
-
-- [ ] Feature works in light and dark themes
-- [ ] Error cases show user-friendly messages
-- [ ] Keyboard navigation works
-- [ ] No console errors in Developer Tools
+1. Run `npm run check-types`.
+2. Run `npm run compile`.
+3. Run `npm run lint` for command and extension changes.
+4. Run `npm run compile-tests` when you add or update tests.
+5. Launch the Extension Development Host with `F5` for manual verification.
 
 ## Code Style Guidelines
 
-1. **TypeScript strict mode** - Fix all type errors
-2. **Use existing patterns** - Follow conventions in similar files
-3. **Escape HTML** - Always use `escapeHtml()` for dynamic content
-4. **Use design system** - Use component classes from `components.css`
-5. **Handle errors** - Use `handleCloudinaryError()` for API errors
-6. **Document** - Add JSDoc comments for public functions
+1. Keep command registration patterns consistent with `src/commands/registerCommands.ts`.
+2. Use `CloudinaryService` for Cloudinary state and API access.
+3. Keep webview host logic in `src/webview/*.ts` and browser-side logic in `src/webview/client/*.ts`.
+4. Use `handleCloudinaryError()` for Cloudinary API failures.
+5. Prefer narrowing documentation claims over describing behavior that is not implemented.
diff --git a/docs/architecture.md b/docs/architecture.md
index 015952a..0d198b6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,30 +1,30 @@
 # Architecture
 
-The extension is built on VS Code's extension API and integrates with Cloudinary's Admin and Upload APIs.
+The extension is a VS Code sidebar integration built around a shared `CloudinaryService` plus webview-based UI surfaces.
 
-### Core Components
+## Core Components
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
-│                     VS Code Extension                        │
+│                     VS Code Extension                       │
 ├─────────────────────────────────────────────────────────────┤
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
-│  │  Tree View   │  │   Webviews   │  │   Commands   │       │
-│  │  (Sidebar)   │  │  (Panels)    │  │  (Actions)   │       │
+│  │ Homescreen   │  │   Library    │  │   Commands   │       │
+│  │  Webview     │  │   Webview    │  │   & Panels   │       │
 │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
 │         │                 │                 │               │
 │         └────────────┬────┴────────────────┘               │
 │                      │                                      │
 │         ┌────────────▼────────────┐                        │
-│         │  CloudinaryTreeProvider │                        │
-│         │  (State & API Layer)    │                        │
+│         │    CloudinaryService    │                        │
+│         │  State + API boundary   │                        │
 │         └────────────┬────────────┘                        │
 │                      │                                      │
 ├──────────────────────┼──────────────────────────────────────┤
 │                      │                                      │
 │         ┌────────────▼────────────┐                        │
-│         │    Cloudinary SDK       │                        │
-│         │    (Node.js v2)         │                        │
+│         │ Cloudinary SDK Adapter  │                        │
+│         │  wraps Node SDK usage   │                        │
 │         └────────────┬────────────┘                        │
 │                      │                                      │
 └──────────────────────┼──────────────────────────────────────┘
@@ -37,17 +37,13 @@ The extension is built on VS Code's extension API and integrates with Cloudinary
            └───────────────────────┘
 ```
 
-### Key Design Decisions
-
-1. **Configuration via files, not settings** - API secrets are stored in `~/.cloudinary/environments.json`, not VS Code settings (which could be committed to repos)
-
-2. **Singleton provider** - `CloudinaryTreeDataProvider` holds all state and manages API calls
-
-3. **External CSS/JS for webviews** - Styles and scripts are loaded from files, not embedded in HTML strings
+## Key Design Decisions
 
-4. **Centralized icons** - SVG icons are defined once in `src/webview/icons.ts`
-
-5. **Shared utilities** - Common functions like `escapeHtml` are in `src/webview/utils/helpers.ts`
+1. Configuration lives in Cloudinary environment files, not VS Code settings.
+2. `CloudinaryService` owns runtime Cloudinary state such as credentials, folder mode, and upload presets.
+3. The sidebar is webview-driven: `cloudinaryHomescreen` and `cloudinaryMediaLibrary` are both webview views.
+4. Webview host code lives in `src/webview/*.ts`; browser-side behavior lives in `src/webview/client/*.ts`.
+5. The Cloudinary SDK is wrapped behind `createCloudinarySdkAdapter()` so service logic stays testable.
 
 ## Technology Stack
 
@@ -56,85 +52,89 @@ The extension is built on VS Code's extension API and integrates with Cloudinary
 | Language | TypeScript (strict mode) |
 | Build | esbuild |
 | Runtime | VS Code Extension Host (Node.js) |
-| API Client | Cloudinary Node.js SDK v2.x |
+| API Client | Cloudinary Node.js SDK v2.x via adapter |
 | Testing | Mocha + VS Code Test Electron |
 | Linting | ESLint |
 
 ## Data Flow
 
-### Configuration Loading
+### Activation and Configuration
 
-```
+```text
 1. Extension activates
-2. Check for workspace config (.cloudinary/environments.json)
-3. Fall back to global config (~/.cloudinary/environments.json)
-4. Validate credentials (reject placeholder values)
-5. Configure Cloudinary SDK
-6. Detect folder mode (dynamic vs fixed)
+2. Load environments from .cloudinary/environments.json or ~/.cloudinary/environments.json
+3. Validate credentials and configure the Cloudinary SDK
+4. Detect folder mode and cache it in global state
+5. Create shared CloudinaryService
+6. Register homescreen and library webview providers
+7. Register commands against the shared service/providers
 ```
 
-### Tree View Population
+### Library Loading
 
-```
-1. VS Code calls provider.getChildren()
-2. Provider checks cache (assetMap)
-3. If not cached, fetch from API
-4. Transform to CloudinaryItem instances
-5. Return items to VS Code
+```text
+1. Library webview posts "ready"
+2. LibraryWebviewViewProvider reads current view state
+3. Provider calls CloudinaryService for folders/assets/search results
+4. Provider posts root/search/folder messages to the client
+5. Client renders the virtualized tree/list UI
 ```
 
+The library renders a compact header (brand strip, action toolbar, filter controls, and search field) above the virtualized list:
+
+- **Brand strip** — Cloudinary logo, wordmark, and active cloud name pill. The pill is populated from the `envChanged` message posted on `ready` and on every environment switch.
+- **Action toolbar** — icon-button groups for navigation, refresh, upload, and configuration. Search and filtering are not toolbar toggles; those controls remain visible below the toolbar.
+- **Search and filter controls** — resource type, sort order, and search input stay visible so the core browse controls are always one interaction away.
+- **Row grid** — every row is 22px tall with three uniform 18px slots (twistie · icon · spacer) so folders, assets, loading, and clear-search rows share an exact rhythm. Row content is flex-centered so glyphs and labels sit in the middle of the selection band.
+- **Folder iconography** — separate closed (stroked outline) and open (filled, two-tone) glyphs so expand state reads from the icon as well as the chevron rotation.
+- **Authenticated delivery** — assets with `type: authenticated` are marked with a lock in the list and preview. The service signs the original delivery URL and reuses it for preview fields instead of generating dynamic optimization/thumbnail transformations.
+- **Hover preview** — narrow card with a brand-gradient hairline, 176×176 thumbnail, resource-type chip, and truncated caption. Smart left/right placement based on viewport edges.
+- **Welcome empty state** — gradient-edged card shown when no credentials are configured; CTA button posts `runToolbar` `openGlobalConfig`.
+- **Reduced motion** — all animations and transitions are disabled under `@media (prefers-reduced-motion: reduce)`.
+
 ### Webview Communication
 
-```
-Extension                          Webview
-    │                                  │
-    │  panel.webview.html = ...        │
-    │──────────────────────────────────>│
-    │                                  │
-    │  vscode.postMessage({...})       │
-    │<──────────────────────────────────│
-    │                                  │
-    │  panel.webview.postMessage({...})│
-    │──────────────────────────────────>│
-    │                                  │
+```text
+Extension host                     Webview client
+     │                                  │
+     │ webview.html = ...               │
+     │─────────────────────────────────>│
+     │                                  │
+     │ postMessage({ command: ... })    │
+     │─────────────────────────────────>│
+     │                                  │
+     │ onDidReceiveMessage(...)         │
+     │<─────────────────────────────────│
 ```
 
+The homescreen drives navigation and search entry points. The library handles browsing, filtering, sorting, selection, context actions, and scroll state.
+
+Both webview view providers route outbound messages through a defensive `safePost` helper that swallows `Webview is disposed` errors. This protects against late callbacks (search prefetches, upload progress, env-change refreshes) firing after a view collapses or the user dismisses an editor panel.
+
 ## VS Code Integration Points
 
-### Package.json Contributions
+### `package.json` Contributions
 
 | Contribution | Purpose |
 |--------------|---------|
-| `viewsContainers.activitybar` | Cloudinary icon in sidebar |
-| `views.cloudinary` | Tree view registration |
-| `commands` | Command definitions |
-| `menus.view/title` | Tree view title bar buttons |
-| `menus.view/item/context` | Right-click context menu |
-
-### Tree Item Context Values
+| `viewsContainers.activitybar` | Cloudinary icon in the activity bar |
+| `views.cloudinary` | Registers the homescreen and library webview views |
+| `commands` | Command definitions used by webviews and panels |
 
-| Context Value | Description |
-|---------------|-------------|
-| `asset` | Media file (enables copy commands) |
-| `folder` | Directory (enables upload to folder) |
-| `loadMore` | Pagination trigger |
-| `clearSearch` | Clear search results |
+Most toolbar and context actions are now implemented inside the library webview rather than through `contributes.menus`.
 
 ## Error Handling
 
-All Cloudinary API errors flow through `handleCloudinaryError()`:
+Cloudinary-facing failures should go through `handleCloudinaryError()`:
 
 ```typescript
-import { handleCloudinaryError } from '../utils/cloudinaryErrorHandler';
+import { handleCloudinaryError } from "../utils/cloudinaryErrorHandler";
 
 try {
-  await cloudinary.search.execute();
+  await cloudinaryService.searchAssets("hero");
 } catch (err: any) {
-  handleCloudinaryError('Failed to search assets', err);
+  handleCloudinaryError("Failed to search assets", err);
 }
 ```
 
-The handler:
-1. Extracts message from various error formats
-2. Shows VS Code error notification
-3. Offers "Open Global Config" action for credential errors
+The handler normalizes Cloudinary SDK errors and surfaces user-facing actions for common credential problems.
diff --git a/docs/project-structure.md b/docs/project-structure.md
index 4de1ddd..3366833 100644
--- a/docs/project-structure.md
+++ b/docs/project-structure.md
@@ -1,23 +1,24 @@
 # Project Structure
 
-This document explains the organization of the Cloudinary VS Code Extension codebase.
+This document describes the current organization of the Cloudinary VS Code extension after the move to webview-based sidebar views.
 
 ## Directory Overview
 
-```
+```text
 cloudinary-vscode/
 ├── src/                        # TypeScript source code
 │   ├── extension.ts            # Extension entry point
-│   ├── commands/               # Command implementations
-│   ├── tree/                   # Tree view (sidebar)
+│   ├── cloudinary/             # Service layer and SDK adapter
+│   ├── commands/               # Command registrations and handlers
 │   ├── config/                 # Configuration utilities
 │   ├── utils/                  # Shared utilities
-│   ├── webview/                # Webview design system
+│   ├── webview/                # Webview hosts, client code, and design system
 │   └── test/                   # Test files
-├── dist/                       # Bundled output (esbuild)
-├── out/                        # TypeScript output (for tests)
+├── media/                      # Built webview CSS and JS assets
+├── dist/                       # Bundled extension output
+├── out/                        # TypeScript output for tests
 ├── docs/                       # Documentation
-├── resources/                  # Static assets (icons)
+├── resources/                  # Static assets and icons
 ├── package.json                # Extension manifest
 ├── tsconfig.json               # TypeScript configuration
 ├── esbuild.js                  # Build script
@@ -28,193 +29,173 @@ cloudinary-vscode/
 
 ### Entry Point
 
-**`extension.ts`** - Extension lifecycle management
+**`extension.ts`** initializes the shared runtime:
+
+- creates `CloudinaryService`
+- loads Cloudinary environment credentials
+- detects folder mode
+- registers `HomescreenViewProvider`
+- registers `LibraryWebviewViewProvider`
+- registers commands against the shared service and providers
+
+### Cloudinary Layer (`src/cloudinary/`)
 
-- `activate()` - Called when extension starts
-- Creates `CloudinaryTreeDataProvider`
-- Loads configuration
-- Registers commands and tree view
+| File | Purpose |
+|------|---------|
+| `cloudinaryService.ts` | Shared Cloudinary state and high-level operations |
+| `cloudinarySdkAdapter.ts` | Adapter that wraps the Cloudinary SDK |
+| `types.ts` | Shared Cloudinary-facing types |
 
 ### Commands (`src/commands/`)
 
-Each file exports a registration function:
+Each file exports a registration function.
 
 | File | Commands | Purpose |
 |------|----------|---------|
-| `registerCommands.ts` | - | Central registration, imports all commands |
+| `registerCommands.ts` | - | Central registration entry point |
 | `previewAsset.ts` | `cloudinary.openAsset` | Asset preview panel |
 | `uploadWidget.ts` | `cloudinary.openUploadWidget`, `cloudinary.uploadToFolder` | Upload panel |
-| `welcomeScreen.ts` | `cloudinary.showWelcome` | Welcome/onboarding screen |
-| `searchAssets.ts` | `cloudinary.searchAssets` | Search by public ID |
-| `copyCommands.ts` | `cloudinary.copyPublicId`, `cloudinary.copySecureUrl` | Clipboard operations |
+| `welcomeScreen.ts` | `cloudinary.openWelcomeScreen` | Welcome/onboarding panel |
+| `searchAssets.ts` | `cloudinary.searchAssets` | Focus homescreen search |
+| `copyCommands.ts` | `cloudinary.copyPublicId`, `cloudinary.copyUrl`, `cloudinary.copyOptimizedUrl` | Clipboard operations |
 | `switchEnvironment.ts` | `cloudinary.switchEnvironment` | Environment switching |
-| `clearSearch.ts` | `cloudinary.clearSearch` | Clear search filter |
-| `viewOptions.ts` | `cloudinary.setResourceFilter` | Filter by type |
+| `clearSearch.ts` | `cloudinary.clearSearch` | Clear library search |
+| `viewOptions.ts` | `cloudinary.viewOptions` | Filter and sort library contents |
+| `configureAiTools.ts` | `cloudinary.configureAiTools` | AI tools setup flow |
 
-### Tree View (`src/tree/`)
-
-| File | Purpose |
-|------|---------|
-| `treeDataProvider.ts` | `TreeDataProvider` implementation, state management, API calls |
-| `cloudinaryItem.ts` | `TreeItem` subclass for assets, folders, and UI elements |
-
-**CloudinaryTreeDataProvider** holds:
-- Credentials (`cloudName`, `apiKey`, `apiSecret`)
-- View state (current folder, search query, filter)
-- Asset cache (`assetMap`)
-- Upload presets
+Command handlers now generally accept `CloudinaryService`, a narrow environment target, or a webview provider rather than a tree provider.
 
 ### Configuration (`src/config/`)
 
 | File | Purpose |
 |------|---------|
-| `configUtils.ts` | Load/validate configuration files |
-| `detectFolderMode.ts` | Detect dynamic vs fixed folder mode |
+| `configUtils.ts` | Load and validate Cloudinary environment files |
+| `detectFolderMode.ts` | Detect dynamic versus fixed folder mode |
 
 ### Utilities (`src/utils/`)
 
 | File | Purpose |
 |------|---------|
-| `cloudinaryErrorHandler.ts` | Consistent error display with VS Code UI |
-| `userAgent.ts` | Generate user agent for API calls |
+| `cloudinaryErrorHandler.ts` | Consistent Cloudinary error handling |
+| `userAgent.ts` | Extension user-agent generation |
 
 ### Webview System (`src/webview/`)
 
-The webview module provides a design system for building consistent UIs:
+The webview module now contains both sidebar views and the reusable UI system used by panels.
 
-```
+```text
 src/webview/
-├── index.ts                    # Public exports
-├── tokens.ts                   # Design tokens (colors, spacing)
-├── baseStyles.ts               # CSS reset, typography
-├── icons.ts                    # Centralized SVG icons
+├── homescreenView.ts           # Sidebar homescreen host
+├── libraryView.ts              # Sidebar media library host
 ├── webviewUtils.ts             # HTML generation helpers
-├── components/                 # UI components
-│   ├── index.ts                # Component exports
-│   ├── button.ts               # Button styles
-│   ├── card.ts                 # Card/panel styles
-│   ├── tabs.ts                 # Tab navigation
-│   ├── input.ts                # Form inputs
-│   ├── dropZone.ts             # File upload drop zone
-│   ├── progressBar.ts          # Progress indicators
-│   ├── badge.ts                # Tags and badges
-│   ├── infoRow.ts              # Key-value display
-│   ├── lightbox.ts             # Image lightbox
-│   └── layout.ts               # Layout components
-├── utils/                      # Webview utilities
-│   ├── index.ts                # Utility exports
-│   ├── helpers.ts              # escapeHtml, formatFileSize, etc.
-│   ├── clipboard.ts            # Clipboard functionality
-│   └── messaging.ts            # VS Code API wrappers
-├── scripts/                    # TypeScript for client-side JS
-│   ├── index.ts
-│   ├── uploadWidget.ts
-│   ├── previewAsset.ts
-│   └── welcomeScreen.ts
-└── media/                      # External CSS/JS files
-    ├── styles/
-    │   ├── tokens.css          # CSS custom properties
-    │   ├── base.css            # Base styles
-    │   └── components.css      # Component styles
-    └── scripts/
-        ├── common.js           # Shared client-side utilities
-        ├── upload-widget.js    # Upload panel functionality
-        └── welcome.js          # Welcome screen functionality
+├── client/                     # Browser-side TypeScript
+│   ├── homescreen.ts
+│   ├── library.ts              # Library main client
+│   ├── libraryIcons.ts         # SVG glyphs (duplicate of host icons.ts subset)
+│   ├── libraryTypes.ts         # Duplicated message-protocol types
+│   ├── libraryVirtualList.ts   # Virtualization math (22px row height)
+│   ├── libraryRowSplice.ts     # Depth-aware splice helper
+│   ├── libraryMenu.ts          # Context menu
+│   ├── libraryHoverPreview.ts  # Hover thumbnail card with metadata
+│   ├── preview.ts
+│   ├── upload-widget.ts
+│   └── welcome.ts
+├── components/                 # Shared styles/helpers for webviews
+├── utils/                      # Webview-side utilities
+├── scripts/                    # Host-side script entry definitions
+├── baseStyles.ts
+├── icons.ts
+├── index.ts
+└── tokens.ts
 ```
 
-See [Webview System](./webview-system.md) for detailed documentation.
+`src/webview/client/` is bundled into `media/scripts/` by `esbuild.js`.
 
 ## Configuration Files
 
 ### `package.json`
 
-Extension manifest defining:
-- Extension metadata (name, version, publisher)
-- Activation events
-- Contributed commands, views, and menus
-- Dependencies
+Defines:
+
+- extension metadata
+- sidebar view contributions
+- command contributions
+- build and test scripts
+
+The sidebar now contributes two webview views: `cloudinaryHomescreen` and `cloudinaryMediaLibrary`.
 
 ### `tsconfig.json`
 
-TypeScript configuration:
-- Strict mode enabled
-- ES2022 target
-- CommonJS modules (for VS Code)
+TypeScript configuration for type checking and test compilation.
 
 ### `esbuild.js`
 
-Build configuration:
-- Entry: `src/extension.ts`
-- Output: `dist/extension.js`
-- Externals: `vscode` module
-- Source maps enabled
+Bundles the extension entry point into `dist/extension.js` and builds the webview client assets into `media/`.
 
 ## Output Directories
 
 ### `dist/`
 
-Production bundle created by esbuild:
-- `extension.js` - Bundled extension code
-- `extension.js.map` - Source map
+Bundled extension output used by VS Code.
 
 ### `out/`
 
-TypeScript compilation output (for tests):
-- Mirrors `src/` structure
-- Used by test runner
+Compiled test output used by the extension-host test runner.
+
+### `media/`
+
+Built JS and CSS consumed by webviews.
 
 ## Resources
 
 ### `resources/`
 
-Static assets:
-- `cloudinary_icon_blue.png` - Extension icon
-- `icon-image.svg`, `icon-video.svg`, `icon-file.svg` - Tree item icons
+Static extension assets such as the Cloudinary icon.
 
 ## Key Patterns
 
 ### Command Registration
 
 ```typescript
-// src/commands/myCommand.ts
 function registerMyCommand(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryService: CloudinaryService
 ) {
   context.subscriptions.push(
     vscode.commands.registerCommand("cloudinary.myCommand", async () => {
+      if (!cloudinaryService.cloudName) {
+        return;
+      }
+
       // Implementation
     })
   );
 }
-export default registerMyCommand;
 ```
 
-### Tree Item Creation
+### Webview HTML Generation
 
 ```typescript
-new CloudinaryItem(
-  'Label',
-  vscode.TreeItemCollapsibleState.Collapsed,
-  'folder',  // type
-  { path: '/products' },  // data
-  cloudName,
-  dynamicFolders
-);
+import {
+  createWebviewDocument,
+  getScriptUri,
+  getStyleUri,
+} from "../webview/webviewUtils";
+
+view.webview.html = createWebviewDocument({
+  title: "My View",
+  webview: view.webview,
+  extensionUri: context.extensionUri,
+  bodyContent: `<div id="root"></div>`,
+  additionalStyles: [getStyleUri(view.webview, context.extensionUri, "my-view.css")],
+  additionalScripts: [getScriptUri(view.webview, context.extensionUri, "my-view.js")],
+});
 ```
 
-### Webview HTML Generation
+### Library Refresh
 
 ```typescript
-import { createWebviewDocument, getScriptUri } from "../webview/webviewUtils";
-
-panel.webview.html = createWebviewDocument({
-  title: "My Panel",
-  webview: panel.webview,
-  extensionUri: context.extensionUri,
-  bodyContent: getHtmlContent(),
-  additionalScripts: [getScriptUri(webview, extensionUri, "my-script.js")],
-  inlineScript: "initCommon(); initMyPanel();",
-});
+await libraryWebview?.refresh();
 ```
 
+Use provider methods instead of relying on removed tree-provider APIs.
diff --git a/docs/setup.md b/docs/setup.md
index 903904a..47053ab 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -85,9 +85,9 @@ npm test
 After making changes, verify:
 
 - [ ] Extension activates without errors
-- [ ] Tree view populates with folders/assets
+- [ ] Media library populates with folders/assets
 - [ ] Commands work from command palette
-- [ ] Context menus appear on correct items
+- [ ] Library context menu appears on asset and folder rows
 - [ ] Webviews display correctly in light and dark themes
 - [ ] Upload functionality works
 - [ ] Error messages are user-friendly
@@ -125,7 +125,7 @@ When debugging the extension:
 |---------|-------------|
 | `Developer: Reload Window` | Reload after code changes |
 | `Developer: Toggle Developer Tools` | Open browser dev tools for webviews |
-| `Cloudinary: Show Welcome` | Test the welcome screen |
+| `Cloudinary: Open Welcome Guide` | Test the welcome screen |
 | `Cloudinary: Upload` | Test the upload panel |
 
 ## Troubleshooting
@@ -136,7 +136,7 @@ When debugging the extension:
 2. Verify `main` in package.json points to `dist/extension.js`
 3. Run `npm run compile` to check for TypeScript errors
 
-### Tree View Empty
+### Media Library Empty
 
 1. Check credentials in config file
 2. Verify network connectivity
@@ -147,4 +147,3 @@ When debugging the extension:
 1. Open Developer Tools (`Help → Toggle Developer Tools`)
 2. Check Console tab for JavaScript errors
 3. Verify Content Security Policy allows your resources
-
diff --git a/docs/webview-system.md b/docs/webview-system.md
index 6b36580..a8c3f9d 100644
--- a/docs/webview-system.md
+++ b/docs/webview-system.md
@@ -1,23 +1,34 @@
 # Webview System
 
-The extension uses a modular design system for building webview UIs. CSS and JavaScript are loaded from external files, providing better maintainability and debugging.
+The extension uses a modular design system for building webview UIs. CSS is loaded from `media/styles/`, and browser-side TypeScript entry points are bundled into `media/scripts/` by `esbuild.js`.
 
 ## Architecture
 
 ```
 src/webview/
-├── media/                      # External files loaded at runtime
-│   ├── styles/
-│   │   ├── tokens.css          # Design tokens (CSS custom properties)
-│   │   ├── base.css            # Reset, typography, utilities
-│   │   └── components.css      # Component styles
-│   └── scripts/
-│       ├── common.js           # Shared utilities (tabs, copy, collapsibles)
-│       ├── upload-widget.js    # Upload-specific functionality
-│       └── welcome.js          # Welcome screen functionality
+├── client/                     # Browser-side TypeScript entry points
+│   ├── common.ts               # Shared webview utilities
+│   ├── homescreen.ts           # Homescreen sidebar client
+│   ├── library.ts              # Media library sidebar client
+│   ├── preview.ts              # Asset preview client
+│   ├── upload-widget.ts        # Upload panel client
+│   └── welcome.ts              # Welcome panel client
 ├── webviewUtils.ts             # HTML generation and CSP helpers
-├── icons.ts                    # Centralized SVG icons
+├── icons.ts                    # Centralized host-side SVG icons
 └── utils/helpers.ts            # Shared utilities (escapeHtml, etc.)
+
+media/
+├── styles/                     # CSS loaded by webviews
+│   ├── tokens.css              # Design tokens (CSS custom properties)
+│   ├── base.css                # Reset, typography, utilities
+│   ├── components.css          # Component styles
+│   └── library.css             # Library-specific styling
+└── scripts/                    # Built browser bundles from src/webview/client/
+    ├── homescreen.js
+    ├── library.js
+    ├── preview.js
+    ├── upload-widget.js
+    └── welcome.js
 ```
 
 ## Creating a Webview
@@ -37,12 +48,12 @@ function openMyPanel(context: vscode.ExtensionContext) {
     {
       enableScripts: true,
       localResourceRoots: [
-        vscode.Uri.joinPath(context.extensionUri, "src", "webview", "media"),
+        vscode.Uri.joinPath(context.extensionUri, "media"),
       ],
     }
   );
 
-  // Optional: Add custom script
+  // Optional: add a bundled client entry from media/scripts/.
   const myScriptUri = getScriptUri(panel.webview, context.extensionUri, "my-script.js");
 
   panel.webview.html = createWebviewDocument({
@@ -52,7 +63,6 @@ function openMyPanel(context: vscode.ExtensionContext) {
     bodyContent: getMyContent(),
     bodyClass: "layout-centered",  // Optional
     additionalScripts: [myScriptUri],  // Optional
-    inlineScript: "initCommon(); initMyPanel();",  // Required
   });
 
   // Handle messages from webview
@@ -64,10 +74,11 @@ function openMyPanel(context: vscode.ExtensionContext) {
 
 ### Key Points
 
-1. **Always call `initCommon()`** in the inline script - this initializes tabs, copy buttons, and collapsibles
-2. **Use `escapeHtml()`** for any dynamic content
-3. **Import icons** from the centralized module
-4. **Specify `localResourceRoots`** to allow loading external files
+1. **Bundle client behavior from `src/webview/client/`** and add the entry point to `esbuild.js`
+2. **Call `initCommon()` from the client entry** when you need tabs, copy buttons, collapsibles, or lightbox behavior
+3. **Use `escapeHtml()`** for any dynamic content
+4. **Import icons** from the centralized module
+5. **Specify `localResourceRoots`** to allow loading external files
 
 ## CSS Architecture
 
@@ -122,48 +133,48 @@ Styles for all UI components:
 | Drop Zone | `.drop-zone`, `.drop-zone--active` |
 | Lightbox | `.lightbox`, `.lightbox__content` |
 
-## JavaScript Architecture
+## Client Script Architecture
 
-### Common Script (`common.js`)
+### Common Client Module (`src/webview/client/common.ts`)
 
-Shared functionality loaded by all webviews:
+Shared functionality imported by webview client entries:
 
-```javascript
-// Initialize all common functionality
-function initCommon() {
-  initVSCode();      // acquireVsCodeApi()
-  initTabs();        // Tab switching
-  initCopyButtons(); // Copy to clipboard
-  initCollapsibles();// Expandable sections
-  initLightbox();    // Image lightbox
-}
+```typescript
+import { initCommon, getVSCode } from "./common";
 
-// Utility functions
-function copyToClipboard(text) { ... }
-function formatFileSize(bytes) { ... }
-function truncateString(str, maxLength) { ... }
+initCommon();
+const vscode = getVSCode();
 ```
 
+`initCommon()` initializes the VS Code API bridge plus shared tabs, copy buttons, collapsibles, and lightbox behavior. The module also exports helpers such as `copyToClipboard(...)`, `formatFileSize(...)`, and `truncateString(...)`.
+
 ### View-Specific Scripts
 
 Each webview can have its own script:
 
 | Script | Purpose | Init Function |
 |--------|---------|---------------|
-| `upload-widget.js` | File uploads, progress, presets | `initUploadWidget(config)` |
+| `homescreen.js` | Sidebar homescreen and AI tools setup | (auto-init) |
+| `library.js` | Sidebar media library browsing UI | (auto-init) |
+| `preview.js` | Asset preview panel behavior | (auto-init) |
+| `upload-widget.js` | File uploads, progress, presets | `initUploadWidget(config)` for server-provided config |
 | `welcome.js` | Welcome screen interactions | (auto-init) |
 
 ### Initialization Pattern
 
-```javascript
-// In inline script
-initCommon();  // Always first
-initUploadWidget({
-  cloudName: "my-cloud",
-  presets: [...]
+```typescript
+// src/webview/client/my-panel.ts
+import { initCommon, getVSCode } from "./common";
+
+initCommon();
+
+document.getElementById("myButton")?.addEventListener("click", () => {
+  getVSCode()?.postMessage({ command: "doSomething" });
 });
 ```
 
+Use `inlineScript` only when the extension host must pass runtime data into the already-loaded client bundle, as the upload panel does with `initUploadWidget({ ... })`.
+
 ## Content Security Policy
 
 The `createWebviewDocument` function generates a secure CSP:
@@ -317,8 +328,8 @@ panel.webview.onDidReceiveMessage((message) => {
 
 ## Adding a New Component
 
-1. **Add styles** to `src/webview/media/styles/components.css`
-2. **Add JavaScript** (if needed) to `src/webview/media/scripts/common.js`
+1. **Add styles** to the relevant file in `media/styles/`
+2. **Add TypeScript** (if needed) to `src/webview/client/`
 3. **Add TypeScript generator** (if complex) to `src/webview/components/`
 4. **Export** from `src/webview/components/index.ts`
 
diff --git a/esbuild.js b/esbuild.js
index c32bb96..22e1db3 100644
--- a/esbuild.js
+++ b/esbuild.js
@@ -26,6 +26,8 @@ async function main() {
       "src/webview/client/upload-widget.ts",
       "src/webview/client/welcome.ts",
       "src/webview/client/homescreen.ts",
+      "src/webview/client/library.ts",
+      "src/webview/client/docs-ai.ts",
     ],
     bundle: true,
     format: "iife",
@@ -60,7 +62,7 @@ const esbuildProblemMatcherPlugin = {
         console.error(`✘ [ERROR] ${text}`);
         if (location == null) return;
         console.error(
-          `    ${location.file}:${location.line}:${location.column}:`
+          `    ${location.file}:${location.line}:${location.column}:`,
         );
       });
       console.log("[watch] build finished");
diff --git a/media/styles/action-toolbar.css b/media/styles/action-toolbar.css
new file mode 100644
index 0000000..382cfbd
--- /dev/null
+++ b/media/styles/action-toolbar.css
@@ -0,0 +1,78 @@
+.cld-action-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 6px 8px;
+  min-height: 40px;
+  border-bottom: 1px solid var(--vscode-widget-border, rgba(255, 255, 255, 0.08));
+}
+
+.cld-action-toolbar__group {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+}
+
+.cld-action-toolbar__group + .cld-action-toolbar__group {
+  margin-left: 6px;
+}
+
+.cld-action-toolbar__group--utility {
+  margin-left: auto;
+}
+
+.cld-action-toolbar__button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: 6px;
+  color: var(--vscode-icon-foreground);
+  cursor: pointer;
+  position: relative;
+  transition:
+    background-color 140ms ease,
+    color 140ms ease,
+    transform 140ms ease;
+}
+
+.cld-action-toolbar__button svg {
+  display: block;
+  width: 16px;
+  height: 16px;
+  transition: transform 140ms ease;
+}
+
+.cld-action-toolbar__button:hover {
+  background: var(--vscode-toolbar-hoverBackground, rgba(90, 93, 94, 0.18));
+  color: var(--vscode-foreground);
+}
+
+.cld-action-toolbar__button:hover svg {
+  transform: translateY(-0.5px);
+}
+
+.cld-action-toolbar__button:active {
+  transform: scale(0.94);
+}
+
+.cld-action-toolbar__button:focus-visible {
+  outline: 1.5px solid var(--vscode-focusBorder);
+  outline-offset: 1px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cld-action-toolbar__button,
+  .cld-action-toolbar__button svg {
+    transition: none;
+  }
+
+  .cld-action-toolbar__button:hover svg,
+  .cld-action-toolbar__button:active {
+    transform: none;
+  }
+}
diff --git a/media/styles/components.css b/media/styles/components.css
index 31aa053..054a9ac 100644
--- a/media/styles/components.css
+++ b/media/styles/components.css
@@ -350,6 +350,7 @@
 .badge {
   display: inline-flex;
   align-items: center;
+  gap: 0.25rem;
   padding: 0.15rem 0.5rem;
   font-size: var(--font-xs);
   font-weight: 500;
@@ -364,6 +365,18 @@
   color: white;
 }
 
+.badge--auth {
+  background-color: color-mix(in srgb, var(--vscode-charts-yellow, #cca700) 18%, var(--vscode-badge-background));
+  color: var(--vscode-foreground);
+  border: 1px solid color-mix(in srgb, var(--vscode-charts-yellow, #cca700) 45%, transparent);
+}
+
+.badge svg {
+  flex: 0 0 auto;
+  width: 0.85rem;
+  height: 0.85rem;
+}
+
 .badge--pill { border-radius: var(--radius-full); }
 
 /* ========================================
@@ -768,6 +781,7 @@
   display: flex;
   align-items: center;
   gap: var(--space-sm);
+  flex-wrap: wrap;
 }
 
 /* Hero section */
diff --git a/media/styles/docs-ai.css b/media/styles/docs-ai.css
new file mode 100644
index 0000000..3225957
--- /dev/null
+++ b/media/styles/docs-ai.css
@@ -0,0 +1,1236 @@
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+html, body {
+  height: 100%;
+  overflow: hidden;
+  font-family: var(--vscode-font-family, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
+  font-size: 13px;
+  color: var(--vscode-foreground);
+  background: var(--vscode-sideBar-background, var(--vscode-editor-background));
+}
+
+.chat-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+
+/* Header / Tab bar */
+.header-wrapper {
+  flex-shrink: 0;
+  position: relative;
+  z-index: 10;
+}
+
+.tab-bar {
+  display: flex;
+  align-items: stretch;
+  border-bottom: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+  min-height: 32px;
+}
+
+.tab-scroll {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+.tab-scroll::-webkit-scrollbar { display: none; }
+
+.tab-item {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0 6px 0 10px;
+  min-width: 0;
+  max-width: 140px;
+  cursor: pointer;
+  border-right: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.06));
+  white-space: nowrap;
+  flex-shrink: 0;
+  transition: background 0.1s;
+  font-size: 11px;
+  color: var(--vscode-descriptionForeground);
+}
+.tab-item:hover {
+  background: var(--vscode-list-hoverBackground, rgba(255,255,255,0.04));
+  color: var(--vscode-foreground);
+}
+.tab-item.active {
+  background: var(--vscode-editor-background, transparent);
+  color: var(--vscode-foreground);
+  border-bottom: 2px solid #4A5FD9;
+}
+
+.tab-title {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.tab-close {
+  background: none;
+  border: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 2px;
+  border-radius: 3px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  transition: opacity 0.12s, background 0.12s;
+  flex-shrink: 0;
+}
+.tab-item:hover .tab-close { opacity: 0.6; }
+.tab-close:hover {
+  opacity: 1;
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.1));
+}
+
+.tab-actions {
+  display: flex;
+  align-items: center;
+  gap: 1px;
+  padding: 0 4px;
+  flex-shrink: 0;
+  border-left: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.06));
+}
+
+.tab-action-btn {
+  background: none;
+  border: none;
+  color: var(--vscode-foreground);
+  cursor: pointer;
+  padding: 4px;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0.6;
+  transition: opacity 0.15s, background 0.15s;
+}
+.tab-action-btn:hover {
+  opacity: 1;
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.1));
+}
+
+#more-btn,
+#more-menu {
+  display: none !important;
+}
+
+/* History dropdown */
+.history-dropdown {
+  display: none;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  max-height: 70vh;
+  background: var(--vscode-sideBar-background, var(--vscode-editor-background));
+  border-bottom: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+  box-shadow: 0 8px 24px rgba(0,0,0,0.35);
+  flex-direction: column;
+}
+
+.history-search-row {
+  padding: 10px 12px 8px;
+  flex-shrink: 0;
+}
+
+.history-search {
+  width: 100%;
+  background: var(--vscode-input-background, #3c3c3c);
+  color: var(--vscode-input-foreground, #fff);
+  border: 1px solid var(--vscode-input-border, rgba(255,255,255,0.1));
+  border-radius: 4px;
+  padding: 6px 10px;
+  font-size: 12px;
+  font-family: inherit;
+  outline: none;
+}
+.history-search:focus {
+  border-color: #4A5FD9;
+}
+.history-search::placeholder {
+  color: var(--vscode-input-placeholderForeground, rgba(255,255,255,0.4));
+}
+
+.history-list {
+  overflow-y: auto;
+  flex: 1;
+  padding-bottom: 6px;
+}
+
+.history-footer {
+  flex-shrink: 0;
+  margin: 0 10px 10px;
+  padding-top: 8px;
+  border-top: 1px solid var(--vscode-panel-border, rgba(128, 128, 128, 0.14));
+}
+
+.history-clear-all {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: 100%;
+  min-height: 30px;
+  padding: 6px 8px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--vscode-descriptionForeground);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 11.5px;
+  line-height: 1.2;
+  transition: color 0.12s ease, background 0.12s ease;
+}
+
+.history-clear-all:hover {
+  color: var(--vscode-errorForeground, #f44);
+  background: rgba(239, 68, 68, 0.12);
+}
+
+.history-clear-all:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: -1px;
+}
+
+.docs-ai-confirm-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  background: rgba(0, 0, 0, 0.58);
+  opacity: 0;
+  transition: opacity 0.14s ease;
+}
+
+.docs-ai-confirm-overlay.is-visible {
+  opacity: 1;
+}
+
+.docs-ai-confirm-dialog {
+  width: min(320px, calc(100vw - 40px));
+  padding: 20px;
+  border: 1px solid var(--vscode-editorWidget-border, rgba(255, 255, 255, 0.18));
+  border-radius: 8px;
+  background: var(--vscode-editorWidget-background, #252526);
+  box-shadow: 0 20px 44px rgba(0, 0, 0, 0.42);
+  color: var(--vscode-foreground);
+  transform: translateY(4px);
+  transition: transform 0.14s ease;
+}
+
+.docs-ai-confirm-overlay.is-visible .docs-ai-confirm-dialog {
+  transform: translateY(0);
+}
+
+.docs-ai-confirm-title {
+  margin: 0 0 8px;
+  color: var(--vscode-foreground);
+  font-size: 16px;
+  font-weight: 700;
+  line-height: 1.25;
+}
+
+.docs-ai-confirm-message {
+  margin: 0;
+  color: var(--vscode-descriptionForeground);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.docs-ai-confirm-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 20px;
+}
+
+.docs-ai-confirm-btn {
+  min-height: 32px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 6px;
+  color: var(--vscode-button-foreground, #fff);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.docs-ai-confirm-cancel {
+  background: var(--vscode-button-secondaryBackground, rgba(255, 255, 255, 0.12));
+  color: var(--vscode-button-secondaryForeground, var(--vscode-foreground));
+}
+
+.docs-ai-confirm-cancel:hover {
+  background: var(--vscode-button-secondaryHoverBackground, rgba(255, 255, 255, 0.18));
+}
+
+.docs-ai-confirm-delete {
+  background: #dc2626;
+  color: #fff;
+}
+
+.docs-ai-confirm-delete:hover {
+  background: #ef4444;
+}
+
+.docs-ai-confirm-btn:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: 2px;
+}
+
+.history-empty {
+  padding: 24px 16px;
+  text-align: center;
+  color: var(--vscode-descriptionForeground);
+  font-size: 12px;
+}
+
+.history-group {
+  padding-bottom: 2px;
+}
+
+.history-group-label {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--vscode-descriptionForeground);
+  padding: 10px 12px 4px;
+}
+
+.history-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 12px;
+  cursor: pointer;
+  transition: background 0.1s;
+}
+.history-item:hover {
+  background: var(--vscode-list-hoverBackground, rgba(255,255,255,0.04));
+}
+.history-item.active {
+  background: rgba(74, 95, 217, 0.15);
+}
+
+.history-title {
+  flex: 1;
+  min-width: 0;
+  font-size: 12px;
+  color: var(--vscode-foreground);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.history-time {
+  font-size: 10px;
+  color: var(--vscode-descriptionForeground);
+  flex-shrink: 0;
+  opacity: 0.7;
+}
+
+.history-actions {
+  display: flex;
+  gap: 1px;
+  flex-shrink: 0;
+  opacity: 0;
+  transition: opacity 0.12s;
+}
+.history-item:hover .history-actions { opacity: 1; }
+.history-item:hover .history-time { display: none; }
+
+.history-action {
+  background: none;
+  border: none;
+  color: var(--vscode-descriptionForeground);
+  cursor: pointer;
+  padding: 3px;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: color 0.12s, background 0.12s;
+}
+.history-action:hover {
+  color: var(--vscode-foreground);
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.1));
+}
+.history-delete:hover {
+  color: var(--vscode-errorForeground, #f44);
+}
+
+.history-rename-input {
+  flex: 1;
+  min-width: 0;
+  background: var(--vscode-input-background, #3c3c3c);
+  color: var(--vscode-input-foreground, #fff);
+  border: 1px solid #4A5FD9;
+  border-radius: 3px;
+  padding: 3px 6px;
+  font-size: 12px;
+  font-family: inherit;
+  outline: none;
+}
+
+/* Conversation */
+#conversation {
+  flex: 1;
+  overflow-y: auto;
+  padding: 10px 10px 10px;
+}
+
+#conversation.empty-state {
+  display: flex;
+  flex-direction: column;
+}
+
+.empty {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 24px 16px;
+  text-align: center;
+  color: var(--vscode-descriptionForeground);
+  gap: 20px;
+}
+
+.empty-heading {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--vscode-foreground);
+  letter-spacing: -0.01em;
+}
+
+.empty-sub {
+  font-size: 12.5px;
+  color: var(--vscode-descriptionForeground);
+  margin-top: -8px;
+}
+
+.chips { display: flex; flex-direction: column; gap: 6px; width: 100%; align-items: center; }
+
+.chip {
+  background: #4A5FD9;
+  color: #fff;
+  border: none;
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 12px;
+  cursor: pointer;
+  text-align: left;
+  transition: opacity 0.15s;
+}
+.chip:hover {
+  opacity: 0.85;
+}
+
+/* Recent conversations in empty state */
+.recent-chats {
+  flex-shrink: 0;
+  padding: 12px 16px 16px;
+  border-top: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+}
+.recent-heading {
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--vscode-descriptionForeground);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 8px;
+}
+.recent-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 8px 10px;
+  background: none;
+  border: none;
+  border-radius: 6px;
+  color: var(--vscode-foreground);
+  font-size: 12px;
+  cursor: pointer;
+  text-align: left;
+  transition: background 0.1s;
+}
+.recent-item:hover {
+  background: var(--vscode-list-hoverBackground, rgba(255,255,255,0.04));
+}
+.recent-icon {
+  flex-shrink: 0;
+  opacity: 0.5;
+}
+.recent-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.recent-time {
+  flex-shrink: 0;
+  font-size: 10px;
+  color: var(--vscode-descriptionForeground);
+}
+
+/* Empty state centered input */
+.empty-input-row {
+  position: relative;
+  width: 100%;
+  margin-top: 4px;
+}
+
+.empty-input {
+  width: 100%;
+  background: var(--vscode-input-background, #3c3c3c);
+  color: var(--vscode-input-foreground, #fff);
+  border: 1px solid var(--vscode-input-border, rgba(255,255,255,0.15));
+  border-radius: 12px;
+  padding: 14px 46px 40px 14px;
+  font-size: 13.5px;
+  font-family: inherit;
+  outline: none;
+  resize: none;
+  overflow-y: auto;
+  min-height: 100px;
+  max-height: 200px;
+  line-height: 1.5;
+}
+.empty-input:focus {
+  border-color: #4A5FD9;
+}
+.empty-input::placeholder {
+  color: var(--vscode-input-placeholderForeground, rgba(255,255,255,0.4));
+}
+
+.empty-send-btn {
+  position: absolute;
+  right: 8px;
+  bottom: 10px;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #4A5FD9;
+  color: #fff;
+  transition: opacity 0.15s;
+}
+.empty-send-btn:hover { opacity: 0.85; }
+.empty-send-btn:disabled { opacity: 0.3; cursor: default; }
+
+/* Messages */
+.message { margin-bottom: 14px; }
+
+.message.user-message {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+}
+
+.message-meta {
+  margin-bottom: 5px;
+  padding-left: 2px;
+}
+
+.role-label {
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--vscode-descriptionForeground);
+}
+
+.message-meta.right {
+  text-align: right;
+  padding-right: 2px;
+  padding-left: 0;
+}
+
+.msg-actions {
+  margin-top: 2px;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 2px;
+  padding-right: 2px;
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+.message:hover .msg-actions {
+  opacity: 1;
+}
+
+.msg-actions-group {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+}
+
+.msg-actions-sep {
+  width: 1px;
+  height: 14px;
+  background: var(--vscode-widget-border, rgba(255,255,255,0.12));
+  margin: 0 4px;
+}
+
+.msg-copy, .msg-feedback {
+  background: none;
+  border: none;
+  padding: 4px;
+  cursor: pointer;
+  color: var(--vscode-descriptionForeground);
+  display: inline-flex;
+  align-items: center;
+  border-radius: 4px;
+  transition: color 0.15s, background 0.15s;
+}
+
+.msg-copy:hover, .msg-feedback:hover {
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.1));
+  color: var(--vscode-foreground);
+}
+
+.msg-copy.copied {
+  color: var(--vscode-terminal-ansiGreen, #4ec9b0);
+}
+
+.msg-feedback-up.selected {
+  color: var(--vscode-terminal-ansiGreen, #4ec9b0);
+}
+
+.msg-feedback-down.selected {
+  color: var(--vscode-errorForeground, #f44);
+}
+
+/* Feedback form (downvote) */
+.feedback-form {
+  margin-top: 6px;
+  animation: feedbackSlideIn 0.15s ease-out;
+}
+
+@keyframes feedbackSlideIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.feedback-form-inner {
+  background: var(--vscode-editorWidget-background, #252526);
+  border: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.1));
+  border-radius: 8px;
+  padding: 12px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.feedback-form-header {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--vscode-foreground);
+}
+
+.feedback-stars {
+  display: flex;
+  gap: 2px;
+}
+
+.feedback-star {
+  background: none;
+  border: none;
+  padding: 2px;
+  cursor: pointer;
+  color: var(--vscode-descriptionForeground);
+  display: flex;
+  align-items: center;
+  border-radius: 3px;
+  transition: color 0.12s, transform 0.12s;
+}
+
+.feedback-star:hover {
+  transform: scale(1.15);
+}
+
+.feedback-star.active {
+  color: #e8a317;
+}
+
+.feedback-comment {
+  width: 100%;
+  min-height: 56px;
+  max-height: 120px;
+  padding: 8px 10px;
+  background: var(--vscode-input-background, #3c3c3c);
+  color: var(--vscode-input-foreground, #fff);
+  border: 1px solid var(--vscode-input-border, rgba(255,255,255,0.1));
+  border-radius: 6px;
+  font-size: 12px;
+  font-family: inherit;
+  line-height: 1.5;
+  resize: vertical;
+  outline: none;
+}
+
+.feedback-comment:focus {
+  border-color: #4A5FD9;
+}
+
+.feedback-comment::placeholder {
+  color: var(--vscode-input-placeholderForeground, rgba(255,255,255,0.4));
+}
+
+.feedback-form-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+}
+
+.feedback-cancel-btn,
+.feedback-submit-btn {
+  padding: 5px 12px;
+  border-radius: 5px;
+  font-size: 12px;
+  font-family: inherit;
+  cursor: pointer;
+  border: none;
+  transition: background 0.12s;
+}
+
+.feedback-cancel-btn {
+  background: rgba(255,255,255,0.08);
+  color: var(--vscode-foreground);
+}
+.feedback-cancel-btn:hover {
+  background: rgba(255,255,255,0.12);
+}
+
+.feedback-submit-btn {
+  background: #4A5FD9;
+  color: #fff;
+}
+.feedback-submit-btn:hover {
+  opacity: 0.9;
+}
+
+.feedback-thankyou {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 0;
+  color: var(--vscode-terminal-ansiGreen, #4ec9b0);
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.bubble.user {
+  cursor: pointer;
+}
+
+.bubble.user.editing {
+  cursor: default;
+  background: var(--vscode-input-background, #3c3c3c) !important;
+  color: var(--vscode-input-foreground, #fff) !important;
+  border: 1px solid #4A5FD9;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.edit-input-row {
+  display: flex;
+  align-items: flex-end;
+  gap: 6px;
+}
+
+.edit-textarea {
+  flex: 1;
+  padding: 0;
+  margin: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: 1.55;
+  resize: none;
+  box-sizing: border-box;
+  overflow: hidden;
+}
+
+.edit-send-btn {
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #4A5FD9;
+  color: #fff;
+  transition: opacity 0.15s;
+}
+.edit-send-btn:hover { opacity: 0.85; }
+.edit-send-btn:disabled { opacity: 0.3; cursor: default; }
+
+
+.bubble {
+  padding: 8px 12px;
+  border-radius: 10px;
+  line-height: 1.55;
+  word-break: break-word;
+}
+
+.bubble.user {
+  background: #4A5FD9;
+  color: #fff;
+  border-radius: 10px 10px 2px 10px;
+  display: inline-block;
+  max-width: 85%;
+}
+.bubble.user[dir="rtl"], .bubble.user:dir(rtl) {
+  border-radius: 10px 10px 10px 2px;
+}
+
+.bubble.assistant {
+  background: var(--vscode-editorWidget-background, rgba(255,255,255,0.05));
+  border: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+  border-radius: 10px 10px 10px 2px;
+}
+
+.bubble.error {
+  border-color: var(--vscode-errorForeground, #f44);
+  color: var(--vscode-errorForeground, #f44);
+}
+
+.bubble p { margin: 0.15rem 0; }
+
+.muted {
+  opacity: 0.5;
+  font-style: italic;
+}
+
+.cursor {
+  animation: blink 0.8s steps(2) infinite;
+  color: var(--vscode-editorCursor-foreground, #fff);
+  font-weight: 700;
+  margin-left: 2px;
+}
+@keyframes blink { 50% { opacity: 0; } }
+
+/* Markdown content */
+.md { line-height: 1.6; }
+.md h1 { font-size: 1.3rem; font-weight: 700; margin: 0.5rem 0 0.2rem; }
+.md h2 { font-size: 1.15rem; font-weight: 600; margin: 0.4rem 0 0.15rem; }
+.md h3 { font-size: 1.05rem; font-weight: 600; margin: 0.3rem 0 0.1rem; }
+.md p { margin: 0.2rem 0; }
+.md ul, .md ol { margin: 0.2rem 0; padding-inline-start: 1.4rem; }
+.md li { margin: 0.05rem 0; }
+.md ul li { list-style: disc; }
+.md ol li { list-style: decimal; }
+.md strong { font-weight: 700; color: var(--vscode-foreground); }
+.md em { font-style: italic; }
+.md a {
+  color: #4A5FD9;
+  text-decoration: none;
+}
+.md a:hover { text-decoration: underline; }
+
+.md code:not(.hljs) {
+  background: var(--vscode-textCodeBlock-background, rgba(255,255,255,0.1));
+  color: var(--vscode-textPreformat-foreground, #d7ba7d);
+  padding: 1px 5px;
+  border-radius: 4px;
+  font-family: var(--vscode-editor-font-family, 'Menlo', monospace);
+  font-size: 0.9em;
+}
+
+/* Code block container */
+.code-block {
+  position: relative;
+  margin: 0.4rem 0;
+  border-radius: 6px;
+  border: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+  overflow: hidden;
+}
+
+.code-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 8px 4px 12px;
+  background: var(--vscode-editorGroupHeader-tabsBackground, var(--vscode-editorWidget-background));
+  border-bottom: 1px solid var(--vscode-widget-border, rgba(128,128,128,0.2));
+  min-height: 28px;
+}
+
+.code-lang {
+  font-size: 11px;
+  color: var(--vscode-descriptionForeground, rgba(255,255,255,0.5));
+  font-family: inherit;
+  text-transform: lowercase;
+}
+
+.code-copy {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  background: none;
+  border: none;
+  color: var(--vscode-descriptionForeground, rgba(255,255,255,0.5));
+  cursor: pointer;
+  font-size: 11px;
+  font-family: inherit;
+  padding: 2px 6px;
+  border-radius: 3px;
+  transition: color 0.15s, background 0.15s;
+}
+.code-copy:hover {
+  color: var(--vscode-foreground);
+  background: var(--vscode-toolbar-hoverBackground, rgba(255,255,255,0.1));
+}
+.code-copy.copied {
+  color: var(--vscode-terminal-ansiGreen, #4ec9b0);
+}
+
+.code-block pre {
+  margin: 0;
+  border: none;
+  border-radius: 0;
+}
+
+.md pre {
+  background: var(--vscode-textCodeBlock-background, #1e1e1e);
+  padding: 10px 12px;
+  margin: 0.3rem 0;
+  overflow-x: auto;
+  font-family: var(--vscode-editor-font-family, 'Menlo', monospace);
+}
+
+.code-block .md pre,
+.code-block pre {
+  margin: 0;
+  border-radius: 0;
+}
+
+.md pre code {
+  background: none;
+  color: inherit;
+  padding: 0;
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+/* Highlight.js theme — uses VS Code token colors so it adapts to any theme */
+.hljs { color: var(--vscode-editor-foreground); }
+.hljs-keyword,
+.hljs-literal,
+.hljs-symbol,
+.hljs-meta { color: var(--vscode-symbolIcon-keywordForeground, var(--vscode-debugTokenExpression-name)); }
+.hljs-built_in,
+.hljs-type,
+.hljs-title.class_ { color: var(--vscode-symbolIcon-classForeground, var(--vscode-debugTokenExpression-name)); }
+.hljs-number { color: var(--vscode-debugTokenExpression-number, var(--vscode-editor-foreground)); }
+.hljs-string,
+.hljs-regexp,
+.hljs-link { color: var(--vscode-debugTokenExpression-string, var(--vscode-editor-foreground)); }
+.hljs-variable,
+.hljs-template-variable,
+.hljs-selector-id,
+.hljs-attr,
+.hljs-attribute,
+.hljs-params,
+.hljs-property { color: var(--vscode-symbolIcon-variableForeground, var(--vscode-editor-foreground)); }
+.hljs-comment,
+.hljs-quote,
+.hljs-doctag { color: var(--vscode-descriptionForeground); font-style: italic; }
+.hljs-function,
+.hljs-title,
+.hljs-title.function_,
+.hljs-section { color: var(--vscode-symbolIcon-functionForeground, var(--vscode-textLink-foreground)); }
+.hljs-tag,
+.hljs-name { color: var(--vscode-symbolIcon-keywordForeground, var(--vscode-editor-foreground)); }
+.hljs-selector-tag,
+.hljs-selector-class,
+.hljs-bullet { color: var(--vscode-symbolIcon-propertyForeground, var(--vscode-editor-foreground)); }
+.hljs-addition { color: var(--vscode-gitDecoration-addedResourceForeground, green); }
+.hljs-deletion { color: var(--vscode-gitDecoration-deletedResourceForeground, red); }
+.hljs-emphasis { font-style: italic; }
+.hljs-strong { font-weight: bold; }
+.hljs-punctuation,
+.hljs-operator { color: var(--vscode-editor-foreground); }
+
+.md blockquote {
+  border-inline-start: 3px solid var(--vscode-textBlockQuote-border, rgba(255,255,255,0.2));
+  padding: 4px 10px;
+  margin: 0.3rem 0;
+  opacity: 0.85;
+  font-style: italic;
+}
+
+.md table { width: 100%; border-collapse: collapse; margin: 0.3rem 0; font-size: 12px; }
+.md th, .md td {
+  padding: 6px 8px;
+  text-align: start;
+  border-bottom: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+}
+.md th { font-weight: 600; }
+
+.md hr { border: none; height: 1px; background: var(--vscode-widget-border); margin: 0.4rem 0; }
+
+.md .doc-citation {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  margin: 0 1px;
+  padding: 0 5px;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--vscode-textLink-foreground, #3794ff) 18%, transparent);
+  color: var(--vscode-textLink-foreground, #3794ff);
+  font-size: 0.78em;
+  font-weight: 700;
+  line-height: 1;
+  text-decoration: none;
+  vertical-align: baseline;
+  white-space: nowrap;
+}
+
+.md .doc-citation:hover {
+  background: color-mix(in srgb, var(--vscode-textLink-foreground, #3794ff) 28%, transparent);
+  text-decoration: none;
+}
+
+/* Sources */
+.sources { margin-top: 4px; }
+
+.sources-toggle {
+  background: none;
+  border: none;
+  color: var(--vscode-textLink-foreground, #3794ff);
+  cursor: pointer;
+  font-size: 12px;
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 2px 0;
+}
+.sources-toggle:hover { text-decoration: underline; }
+
+.chevron {
+  display: inline-flex;
+  align-items: center;
+  transition: transform 0.2s;
+  font-size: 14px;
+  line-height: 1;
+}
+.chevron-open { transform: rotate(180deg); }
+
+.sources-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 6px;
+}
+
+.source-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 11px;
+  color: var(--vscode-textLink-foreground, #3794ff);
+  text-decoration: none;
+  padding: 3px 6px 3px 4px;
+  border: 1px solid color-mix(in srgb, var(--vscode-textLink-foreground, #3794ff) 24%, transparent);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--vscode-textLink-foreground, #3794ff) 10%, transparent);
+  white-space: nowrap;
+}
+.source-item:hover {
+  background: color-mix(in srgb, var(--vscode-textLink-foreground, #3794ff) 16%, transparent);
+  text-decoration: none;
+}
+.source-item svg { flex-shrink: 0; opacity: 0.6; }
+
+.source-index {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 16px;
+  height: 16px;
+  padding: 0 4px;
+  border-radius: 999px;
+  background: var(--vscode-textLink-foreground, #3794ff);
+  color: var(--vscode-button-foreground, #fff);
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.source-title {
+  overflow: hidden;
+  max-width: 220px;
+  text-overflow: ellipsis;
+}
+
+/* Follow-ups */
+.follow-ups {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  margin-top: 8px;
+}
+
+.follow-up-btn {
+  background: #4A5FD9;
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  padding: 6px 10px;
+  font-size: 12px;
+  cursor: pointer;
+  text-align: left;
+  transition: opacity 0.15s;
+}
+.follow-up-btn:hover {
+  opacity: 0.85;
+}
+
+/* Composer */
+.composer {
+  flex-shrink: 0;
+  padding: 10px 10px 12px;
+  border-top: 1px solid var(--vscode-widget-border, rgba(255,255,255,0.08));
+}
+
+.input-row {
+  position: relative;
+}
+
+#chat-input {
+  width: 100%;
+  background: var(--vscode-input-background, #3c3c3c);
+  color: var(--vscode-input-foreground, #fff);
+  border: 1px solid var(--vscode-input-border, rgba(255,255,255,0.1));
+  border-radius: 10px;
+  padding: 10px 42px 10px 12px;
+  font-size: 13px;
+  font-family: inherit;
+  outline: none;
+  resize: none;
+  overflow-y: auto;
+  min-height: 44px;
+  max-height: 150px;
+  line-height: 1.45;
+}
+#chat-input:focus {
+  border-color: #4A5FD9;
+}
+#chat-input::placeholder {
+  color: var(--vscode-input-placeholderForeground, rgba(255,255,255,0.4));
+}
+
+#send-btn, #stop-btn {
+  position: absolute;
+  right: 7px;
+  bottom: 8px;
+  width: 30px;
+  height: 30px;
+  padding: 0;
+  border: none;
+  border-radius: 7px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: opacity 0.15s, background 0.15s;
+}
+
+#send-btn {
+  background: #4A5FD9;
+  color: #fff;
+}
+#send-btn:hover { opacity: 0.85; }
+#send-btn:disabled { opacity: 0.3; cursor: default; }
+
+#stop-btn {
+  background: rgba(255,255,255,0.15);
+  color: var(--vscode-descriptionForeground, #999);
+  border: 1px solid rgba(255,255,255,0.15);
+  width: 26px;
+  height: 26px;
+  display: none;
+}
+#stop-btn svg { width: 10px; height: 10px; }
+#stop-btn:hover { background: rgba(255,255,255,0.25); }
+
+#disclaimer {
+  font-size: 11px;
+  color: var(--vscode-descriptionForeground);
+  text-align: center;
+  margin-top: 6px;
+}
+
+#disclaimer a {
+  color: #4A5FD9;
+  text-decoration: none;
+}
+#disclaimer a:hover { text-decoration: underline; }
+
+/* Undo Toast */
+.undo-toast {
+  position: fixed;
+  bottom: 80px;
+  left: 50%;
+  transform: translateX(-50%) translateY(20px);
+  background: var(--vscode-editorWidget-background, #1e1e1e);
+  border: 1px solid var(--vscode-editorWidget-border, rgba(255,255,255,0.12));
+  color: var(--vscode-foreground, #ccc);
+  padding: 10px 16px;
+  border-radius: 8px;
+  font-size: 13px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  opacity: 0;
+  transition: opacity 0.2s, transform 0.2s;
+  z-index: 1000;
+  box-shadow: 0 4px 16px rgba(0,0,0,0.3);
+}
+.undo-toast.visible { opacity: 1; transform: translateX(-50%) translateY(0); }
+.undo-btn {
+  background: none;
+  border: none;
+  color: #4A5FD9;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 2px 6px;
+  border-radius: 4px;
+}
+.undo-btn:hover { background: rgba(74, 95, 217, 0.15); }
diff --git a/media/styles/homescreen.css b/media/styles/homescreen.css
index c0eb507..9409600 100644
--- a/media/styles/homescreen.css
+++ b/media/styles/homescreen.css
@@ -2,9 +2,15 @@
  * Homescreen sidebar panel styles.
  */
 
-* { box-sizing: border-box; margin: 0; padding: 0; }
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
 
-body { background: var(--vscode-sideBar-background); }
+body {
+  background: var(--vscode-sideBar-background);
+}
 
 .hs-root {
   display: flex;
@@ -23,21 +29,27 @@ body { background: var(--vscode-sideBar-background); }
   flex-shrink: 0;
   animation: hs-in 0.18s ease both;
 }
+
 .hs-header::before {
   content: '';
   position: absolute;
-  top: -24px; right: -24px;
-  width: 110px; height: 110px;
-  background: rgba(255,255,255,0.06);
+  top: -24px;
+  right: -24px;
+  width: 110px;
+  height: 110px;
+  background: rgba(255, 255, 255, 0.06);
   border-radius: 50%;
   pointer-events: none;
 }
+
 .hs-header::after {
   content: '';
   position: absolute;
-  bottom: -32px; left: 30px;
-  width: 70px; height: 70px;
-  background: rgba(255,255,255,0.04);
+  bottom: -32px;
+  left: 30px;
+  width: 70px;
+  height: 70px;
+  background: rgba(255, 255, 255, 0.04);
   border-radius: 50%;
   pointer-events: none;
 }
@@ -50,18 +62,38 @@ body { background: var(--vscode-sideBar-background); }
   margin-bottom: 10px;
   position: relative;
 }
+
 .hs-brand-left {
   display: flex;
   align-items: center;
   gap: 8px;
 }
-.hs-brand-icon { width: 22px; height: 22px; flex-shrink: 0; }
+
+.hs-brand-logo-wrap {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 22px;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.94);
+  border: 1px solid rgba(255, 255, 255, 0.38);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+  flex-shrink: 0;
+}
+
+.hs-brand-logo {
+  display: block;
+  width: 19px;
+  height: auto;
+}
+
 .hs-brand-name {
   font-size: 11px;
   font-weight: 700;
   letter-spacing: 1.2px;
   text-transform: uppercase;
-  color: rgba(255,255,255,0.95);
+  color: rgba(255, 255, 255, 0.95);
 }
 
 .hs-cloud-row {
@@ -70,12 +102,14 @@ body { background: var(--vscode-sideBar-background); }
   justify-content: space-between;
   position: relative;
 }
+
 .hs-cloud-col {
   display: flex;
   flex-direction: column;
   gap: 3px;
   min-width: 0;
 }
+
 .hs-cloud-name {
   font-size: 15px;
   font-weight: 600;
@@ -85,42 +119,48 @@ body { background: var(--vscode-sideBar-background); }
   white-space: nowrap;
   max-width: 160px;
 }
+
 .hs-cloud-name--placeholder {
   font-size: 13px;
   font-weight: 400;
-  color: rgba(255,255,255,0.6);
+  color: rgba(255, 255, 255, 0.6);
   font-style: italic;
 }
+
 .hs-folder-mode {
   font-size: 10px;
-  color: rgba(255,255,255,0.5);
+  color: rgba(255, 255, 255, 0.5);
   font-weight: 400;
   letter-spacing: 0.2px;
   white-space: nowrap;
 }
+
 .hs-configure-btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
   width: 22px;
   height: 22px;
-  background: rgba(255,255,255,0.1);
-  border: 1px solid rgba(255,255,255,0.12);
+  background: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.12);
   border-radius: 4px;
   cursor: pointer;
-  color: rgba(255,255,255,0.7);
+  color: rgba(255, 255, 255, 0.7);
   flex-shrink: 0;
   transition: background 0.12s, color 0.12s;
   padding: 0;
 }
+
 .hs-configure-btn:hover {
-  background: rgba(255,255,255,0.2);
+  background: rgba(255, 255, 255, 0.2);
   color: #fff;
 }
+
 .hs-configure-btn:focus-visible {
-  outline: 1px solid rgba(255,255,255,0.5);
+  outline: 1px solid rgba(255, 255, 255, 0.5);
   outline-offset: 1px;
 }
+
 .hs-status-pill {
   display: inline-flex;
   align-items: center;
@@ -130,20 +170,23 @@ body { background: var(--vscode-sideBar-background); }
   font-size: 10px;
   font-weight: 500;
   letter-spacing: 0.2px;
-  color: rgba(255,255,255,0.92);
-  background: rgba(255,255,255,0.14);
+  color: rgba(255, 255, 255, 0.92);
+  background: rgba(255, 255, 255, 0.14);
   flex-shrink: 0;
 }
+
 .hs-status-dot {
-  width: 6px; height: 6px;
+  width: 6px;
+  height: 6px;
   border-radius: 50%;
   background: #4ade80;
-  box-shadow: 0 0 5px rgba(74,222,128,0.8);
+  box-shadow: 0 0 5px rgba(74, 222, 128, 0.8);
   flex-shrink: 0;
 }
+
 .hs-status-dot--warn {
   background: #fbbf24;
-  box-shadow: 0 0 5px rgba(251,191,36,0.8);
+  box-shadow: 0 0 5px rgba(251, 191, 36, 0.8);
 }
 
 /* ── Setup banner ── */
@@ -151,18 +194,27 @@ body { background: var(--vscode-sideBar-background); }
   margin: 10px 10px 0;
   padding: 9px 11px;
   border-radius: 8px;
-  background: rgba(251,191,36,0.08);
-  border: 1px solid rgba(251,191,36,0.22);
+  background: rgba(251, 191, 36, 0.08);
+  border: 1px solid rgba(251, 191, 36, 0.22);
   display: flex;
   align-items: center;
   gap: 8px;
   animation: hs-in 0.2s ease both;
 }
+
 .hs-setup-banner-icon {
-  font-size: 13px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--vscode-notificationsWarningIcon-foreground, #fbbf24);
   flex-shrink: 0;
-  line-height: 1;
 }
+
+.hs-setup-banner-icon svg {
+  width: 13px;
+  height: 13px;
+}
+
 .hs-setup-banner-text {
   flex: 1;
   font-size: 11px;
@@ -170,44 +222,52 @@ body { background: var(--vscode-sideBar-background); }
   opacity: 0.85;
   line-height: 1.4;
 }
+
 .hs-setup-banner-btn {
   flex-shrink: 0;
   font-size: 11px;
   font-weight: 600;
   color: #f59e0b;
-  background: rgba(251,191,36,0.14);
-  border: 1px solid rgba(251,191,36,0.3);
+  background: rgba(251, 191, 36, 0.14);
+  border: 1px solid rgba(251, 191, 36, 0.3);
   border-radius: 5px;
   padding: 3px 9px;
   cursor: pointer;
   font-family: var(--vscode-font-family);
   transition: background 0.12s;
 }
-.hs-setup-banner-btn:hover { background: rgba(251,191,36,0.24); }
+
+.hs-setup-banner-btn:hover {
+  background: rgba(251, 191, 36, 0.24);
+}
 
 /* ── Search ── */
 .hs-search {
   padding: 6px 8px 4px;
   animation: hs-in 0.18s ease 0.02s both;
 }
+
 .hs-search-wrap {
   display: flex;
   align-items: center;
   gap: 6px;
   background: var(--vscode-input-background);
-  border: 1px solid var(--vscode-input-border, rgba(128,128,128,0.28));
+  border: 1px solid var(--vscode-input-border, rgba(128, 128, 128, 0.28));
   border-radius: 6px;
   padding: 0 8px;
   transition: border-color 0.15s;
 }
+
 .hs-search-wrap:focus-within {
   border-color: var(--vscode-focusBorder);
 }
+
 .hs-search-icon {
   color: var(--vscode-input-placeholderForeground);
   flex-shrink: 0;
   pointer-events: none;
 }
+
 .hs-search-input {
   flex: 1;
   background: none;
@@ -219,9 +279,11 @@ body { background: var(--vscode-sideBar-background); }
   padding: 5px 0;
   min-width: 0;
 }
+
 .hs-search-input::placeholder {
   color: var(--vscode-input-placeholderForeground);
 }
+
 .hs-search-clear {
   background: none;
   border: none;
@@ -235,11 +297,48 @@ body { background: var(--vscode-sideBar-background); }
   border-radius: 3px;
   transition: color 0.1s;
 }
-.hs-search-clear:hover { color: var(--vscode-foreground); }
+
+.hs-search-clear:hover {
+  color: var(--vscode-foreground);
+}
+
 .hs-search-clear:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
 }
 
+.hs-search-loading {
+  color: var(--vscode-progressBar-background, var(--vscode-focusBorder));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+}
+
+.hs-search-spinner {
+  width: 12px;
+  height: 12px;
+  border: 2px solid rgba(127, 127, 127, 0.35);
+  border-top-color: currentColor;
+  border-radius: 50%;
+  animation: hs-search-spin 720ms linear infinite;
+}
+
+.hs-search--loading .hs-search-clear {
+  display: none;
+}
+
+@keyframes hs-search-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hs-search-spinner {
+    animation: none;
+  }
+}
+
 /* ── Actions ── */
 .hs-actions {
   padding: 8px;
@@ -265,32 +364,61 @@ body { background: var(--vscode-sideBar-background); }
   text-align: left;
   transition: background 0.12s ease;
 }
-.hs-action:hover { background: var(--vscode-list-hoverBackground); }
+
+.hs-action:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
 .hs-action:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
   outline-offset: -1px;
   border-radius: 7px;
 }
+
 .hs-action:disabled {
   cursor: default;
   opacity: 0.55;
 }
-.hs-action:disabled:hover { background: transparent; }
+
+.hs-action:disabled:hover {
+  background: transparent;
+}
 
 .hs-action-icon {
-  width: 30px; height: 30px;
+  width: 30px;
+  height: 30px;
   border-radius: 7px;
   display: flex;
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
 }
-.hs-action-icon--blue  { background: rgba(52,72,197,0.14);  color: #3448C5; }
-.hs-action-icon--green { background: rgba(16,185,129,0.12);  color: #10b981; }
-.hs-action-icon--violet{ background: rgba(139,92,246,0.12);  color: #8b5cf6; }
-.hs-action-icon--amber { background: rgba(245,158,11,0.12);  color: #f59e0b; }
 
-.hs-action-text { flex: 1; min-width: 0; }
+.hs-action-icon--blue {
+  background: rgba(52, 72, 197, 0.14);
+  color: #3448C5;
+}
+
+.hs-action-icon--green {
+  background: rgba(16, 185, 129, 0.12);
+  color: #10b981;
+}
+
+.hs-action-icon--violet {
+  background: rgba(139, 92, 246, 0.12);
+  color: #8b5cf6;
+}
+
+.hs-action-icon--amber {
+  background: rgba(245, 158, 11, 0.12);
+  color: #f59e0b;
+}
+
+.hs-action-text {
+  flex: 1;
+  min-width: 0;
+}
+
 .hs-action-title {
   font-size: 12.5px;
   font-weight: 500;
@@ -300,6 +428,7 @@ body { background: var(--vscode-sideBar-background); }
   overflow: hidden;
   text-overflow: ellipsis;
 }
+
 .hs-action-desc {
   font-size: 10.5px;
   color: var(--vscode-descriptionForeground);
@@ -318,9 +447,9 @@ body { background: var(--vscode-sideBar-background); }
   text-transform: uppercase;
   padding: 2px 6px;
   border-radius: 4px;
-  background: rgba(139,92,246,0.14);
+  background: rgba(139, 92, 246, 0.14);
   color: #8b5cf6;
-  border: 1px solid rgba(139,92,246,0.2);
+  border: 1px solid rgba(139, 92, 246, 0.2);
 }
 
 .hs-chevron {
@@ -329,20 +458,403 @@ body { background: var(--vscode-sideBar-background); }
   opacity: 0.4;
   transition: transform 0.2s;
 }
-.hs-chevron--open { transform: rotate(90deg); }
+
+.hs-chevron--open {
+  transform: rotate(90deg);
+}
 
 .hs-section-divider {
   height: 1px;
   margin: 4px 6px;
-  background: var(--vscode-panel-border, rgba(128,128,128,0.14));
+  background: var(--vscode-panel-border, rgba(128, 128, 128, 0.14));
+}
+
+/* ── Docs AI home launcher ── */
+.hs-docs-ai-home {
+  margin: 10px 0 0;
+  padding: 18px 0 4px;
+  border-top: 1px solid var(--vscode-panel-border, rgba(128,128,128,0.14));
+}
+
+.hs-docs-ai-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 20px;
+  padding: 18px 0 0;
+  text-align: center;
+  color: var(--vscode-descriptionForeground);
+}
+
+.hs-docs-ai-empty-heading {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+  line-height: 1.2;
+  color: var(--vscode-foreground);
+  letter-spacing: 0;
+}
+
+.hs-docs-ai-history-toggle-wrap {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  margin-top: -4px;
+}
+
+.hs-docs-ai-history-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  min-height: 28px;
+  padding: 5px 10px;
+  border: 1px solid var(--vscode-panel-border, rgba(128, 128, 128, 0.18));
+  border-radius: 6px;
+  background: transparent;
+  color: var(--vscode-textLink-foreground);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 11.5px;
+  line-height: 1.2;
+}
+
+.hs-docs-ai-history-toggle:hover,
+.hs-docs-ai-history-toggle.is-active {
+  background: var(--vscode-toolbar-hoverBackground, rgba(128, 128, 128, 0.14));
+  color: var(--vscode-textLink-foreground);
+}
+
+.hs-docs-ai-history-toggle:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: 2px;
+}
+
+.hs-docs-ai-empty-sub {
+  margin: -8px 0 0;
+  font-size: 12.5px;
+  line-height: 1.45;
+  color: var(--vscode-descriptionForeground);
+}
+
+.hs-docs-ai-empty-input-row {
+  position: relative;
+  width: 100%;
+  margin-top: 4px;
+}
+
+.hs-docs-ai-empty-input {
+  width: 100%;
+  min-height: 100px;
+  max-height: 200px;
+  padding: 14px 46px 40px 14px;
+  overflow-y: auto;
+  resize: none;
+  background: var(--vscode-input-background, #3c3c3c);
+  border: 1px solid var(--vscode-input-border, rgba(255,255,255,0.15));
+  border-radius: 12px;
+  outline: none;
+  color: var(--vscode-input-foreground, #fff);
+  font-family: inherit;
+  font-size: 13.5px;
+  line-height: 1.5;
+}
+
+.hs-docs-ai-empty-input:focus {
+  border-color: #4A5FD9;
+}
+
+.hs-docs-ai-empty-input::placeholder {
+  color: var(--vscode-input-placeholderForeground, rgba(255,255,255,0.4));
+}
+
+.hs-docs-ai-empty-send-btn {
+  position: absolute;
+  right: 8px;
+  bottom: 10px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: none;
+  border-radius: 8px;
+  background: #4A5FD9;
+  cursor: pointer;
+  color: #fff;
+  transition: opacity 0.15s;
+}
+
+.hs-docs-ai-empty-send-btn:hover { opacity: 0.85; }
+.hs-docs-ai-empty-send-btn:disabled { opacity: 0.3; cursor: default; }
+
+.hs-docs-ai-chips {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding: 0 0 2px;
+  scroll-snap-type: x proximity;
+  scrollbar-width: none;
+}
+
+.hs-docs-ai-chips::-webkit-scrollbar {
+  display: none;
+}
+
+.hs-docs-ai-chip {
+  flex: 0 0 auto;
+  width: max-content;
+  max-width: none;
+  padding: 8px 12px;
+  border: none;
+  border-radius: 8px;
+  background: #4A5FD9;
+  color: #fff;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 12px;
+  line-height: 1.25;
+  text-align: left;
+  white-space: nowrap;
+  scroll-snap-align: start;
+  transition: opacity 0.15s;
+}
+
+.hs-docs-ai-chip:hover {
+  opacity: 0.85;
+}
+
+.hs-docs-ai-history-panel {
+  width: 100%;
+  margin-top: -2px;
+}
+
+.hs-docs-ai-recent-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.hs-docs-ai-recent-list--expanded {
+  max-height: 260px;
+  overflow-y: auto;
+  padding-right: 2px;
+}
+
+.hs-docs-ai-history-group + .hs-docs-ai-history-group {
+  margin-top: 8px;
+}
+
+.hs-docs-ai-history-group-label {
+  margin: 0 0 3px;
+  padding: 0 2px;
+  font-size: 9.5px;
+  font-weight: 600;
+  letter-spacing: 0.4px;
+  text-transform: uppercase;
+  color: var(--vscode-descriptionForeground);
+  opacity: 0.8;
+}
+
+.hs-docs-ai-history-empty {
+  padding: 8px 2px;
+  color: var(--vscode-descriptionForeground);
+  font-size: 11.5px;
+  text-align: left;
+}
+
+.hs-docs-ai-history-footer {
+  margin-top: 8px;
+  padding-top: 8px;
+  border-top: 1px solid var(--vscode-panel-border, rgba(128, 128, 128, 0.14));
+}
+
+.hs-docs-ai-clear-all {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: 100%;
+  min-height: 30px;
+  padding: 6px 8px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--vscode-descriptionForeground);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 11.5px;
+  line-height: 1.2;
+  transition: color 0.12s ease, background 0.12s ease;
+}
+
+.hs-docs-ai-clear-all:hover {
+  color: var(--vscode-errorForeground, #f44);
+  background: rgba(239, 68, 68, 0.12);
+}
+
+.hs-docs-ai-clear-all:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: -1px;
+}
+
+.docs-ai-confirm-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  background: rgba(0, 0, 0, 0.58);
+  opacity: 0;
+  transition: opacity 0.14s ease;
+}
+
+.docs-ai-confirm-overlay.is-visible {
+  opacity: 1;
+}
+
+.docs-ai-confirm-dialog {
+  width: min(320px, calc(100vw - 40px));
+  padding: 20px;
+  border: 1px solid var(--vscode-editorWidget-border, rgba(255, 255, 255, 0.18));
+  border-radius: 8px;
+  background: var(--vscode-editorWidget-background, #252526);
+  box-shadow: 0 20px 44px rgba(0, 0, 0, 0.42);
+  color: var(--vscode-foreground);
+  transform: translateY(4px);
+  transition: transform 0.14s ease;
+}
+
+.docs-ai-confirm-overlay.is-visible .docs-ai-confirm-dialog {
+  transform: translateY(0);
+}
+
+.docs-ai-confirm-title {
+  margin: 0 0 8px;
+  color: var(--vscode-foreground);
+  font-size: 16px;
+  font-weight: 700;
+  line-height: 1.25;
+}
+
+.docs-ai-confirm-message {
+  margin: 0;
+  color: var(--vscode-descriptionForeground);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.docs-ai-confirm-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 20px;
+}
+
+.docs-ai-confirm-btn {
+  min-height: 32px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 6px;
+  color: var(--vscode-button-foreground, #fff);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.docs-ai-confirm-cancel {
+  background: var(--vscode-button-secondaryBackground, rgba(255, 255, 255, 0.12));
+  color: var(--vscode-button-secondaryForeground, var(--vscode-foreground));
+}
+
+.docs-ai-confirm-cancel:hover {
+  background: var(--vscode-button-secondaryHoverBackground, rgba(255, 255, 255, 0.18));
+}
+
+.docs-ai-confirm-delete {
+  background: #dc2626;
+  color: #fff;
+}
+
+.docs-ai-confirm-delete:hover {
+  background: #ef4444;
+}
+
+.docs-ai-confirm-btn:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: 2px;
+}
+
+.hs-docs-ai-recent-item {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  width: 100%;
+  min-height: 32px;
+  padding: 7px 8px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--vscode-foreground);
+  cursor: pointer;
+  font-family: inherit;
+  text-align: left;
+  transition: background 0.12s ease;
+}
+
+.hs-docs-ai-recent-item:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
+.hs-docs-ai-recent-item:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: -1px;
+}
+
+.hs-docs-ai-recent-icon {
+  flex-shrink: 0;
+  color: var(--vscode-descriptionForeground);
+  opacity: 0.65;
+}
+
+.hs-docs-ai-recent-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 11.5px;
+  line-height: 1.25;
+}
+
+.hs-docs-ai-recent-time {
+  flex-shrink: 0;
+  font-size: 9.5px;
+  color: var(--vscode-descriptionForeground);
+}
+
+.hs-docs-ai-empty-send-btn:focus-visible,
+.hs-docs-ai-chip:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+  outline-offset: 2px;
 }
 
 /* ── Footer ── */
 .hs-footer {
   padding: 8px 16px 12px;
-  border-top: 1px solid var(--vscode-panel-border, rgba(128,128,128,0.12));
+  border-top: 1px solid var(--vscode-panel-border, rgba(128, 128, 128, 0.12));
   animation: hs-in 0.22s ease 0.08s both;
 }
+
 .hs-footer-link {
   display: inline-flex;
   align-items: center;
@@ -356,17 +868,33 @@ body { background: var(--vscode-sideBar-background); }
   font-family: var(--vscode-font-family);
   padding: 0;
 }
-.hs-footer-link:hover { text-decoration: underline; }
-.hs-footer-link:focus-visible { outline: 1px solid var(--vscode-focusBorder); }
+
+.hs-footer-link:hover {
+  text-decoration: underline;
+}
+
+.hs-footer-link:focus-visible {
+  outline: 1px solid var(--vscode-focusBorder);
+}
 
 /* ── Animations ── */
 @keyframes hs-in {
-  from { opacity: 0; transform: translateY(6px); }
-  to   { opacity: 1; transform: translateY(0); }
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
 }
 
 /* ── AI Tools accordion ── */
-#hs-btn-ai-tools { user-select: none; }
+#hs-btn-ai-tools {
+  user-select: none;
+}
+
 #hs-btn-ai-tools.expanded {
   background: var(--vscode-list-hoverBackground);
   border-radius: 7px 7px 0 0;
@@ -377,13 +905,15 @@ body { background: var(--vscode-sideBar-background); }
   max-height: 0;
   transition: max-height 0.28s cubic-bezier(0.4, 0, 0.2, 1);
   border-radius: 0 0 7px 7px;
-  background: rgba(255,255,255,0.02);
+  background: rgba(255, 255, 255, 0.02);
   border-top: 1px solid transparent;
 }
+
 .hs-ai-panel.open {
   max-height: 640px;
-  border-top-color: var(--vscode-panel-border, rgba(128,128,128,0.14));
+  border-top-color: var(--vscode-panel-border, rgba(128, 128, 128, 0.14));
 }
+
 .hs-ai-panel-inner {
   padding: 10px 10px 12px;
   display: flex;
@@ -424,10 +954,11 @@ body { background: var(--vscode-sideBar-background); }
   font-family: var(--vscode-font-family);
   color: var(--vscode-dropdown-foreground);
   background: var(--vscode-dropdown-background);
-  border: 1px solid var(--vscode-dropdown-border, rgba(128,128,128,0.3));
+  border: 1px solid var(--vscode-dropdown-border, rgba(128, 128, 128, 0.3));
   border-radius: 4px;
   cursor: pointer;
 }
+
 .hs-ai-platform-select:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
   outline-offset: 1px;
@@ -448,7 +979,7 @@ body { background: var(--vscode-sideBar-background); }
   align-items: center;
   gap: 2px;
   background: var(--vscode-input-background);
-  border: 1px solid var(--vscode-dropdown-border, rgba(128,128,128,0.3));
+  border: 1px solid var(--vscode-dropdown-border, rgba(128, 128, 128, 0.3));
   border-radius: 5px;
   padding: 2px;
 }
@@ -467,14 +998,17 @@ body { background: var(--vscode-sideBar-background); }
   transition: background 0.12s, color 0.12s;
   white-space: nowrap;
 }
+
 .hs-ai-scope-btn:hover {
   background: var(--vscode-list-hoverBackground);
   color: var(--vscode-foreground);
 }
+
 .hs-ai-scope-btn.active {
   background: var(--vscode-button-background);
   color: var(--vscode-button-foreground);
 }
+
 .hs-ai-scope-btn:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
   outline-offset: -1px;
@@ -500,24 +1034,41 @@ body { background: var(--vscode-sideBar-background); }
 }
 
 /* Loading skeletons */
-.hs-ai-loading { display: flex; flex-direction: column; gap: 6px; }
+.hs-ai-loading {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
 .hs-skeleton {
   height: 22px;
   border-radius: 4px;
-  background: linear-gradient(
-    90deg,
-    rgba(255,255,255,0.04) 0%,
-    rgba(255,255,255,0.09) 50%,
-    rgba(255,255,255,0.04) 100%
-  );
+  background: linear-gradient(90deg,
+      rgba(255, 255, 255, 0.04) 0%,
+      rgba(255, 255, 255, 0.09) 50%,
+      rgba(255, 255, 255, 0.04) 100%);
   background-size: 200% 100%;
   animation: shimmer 1.4s ease infinite;
 }
-.hs-skeleton--short { width: 55%; }
-.hs-skeleton--label { height: 10px; width: 38%; margin-bottom: 4px; }
+
+.hs-skeleton--short {
+  width: 55%;
+}
+
+.hs-skeleton--label {
+  height: 10px;
+  width: 38%;
+  margin-bottom: 4px;
+}
+
 @keyframes shimmer {
-  0%   { background-position: 200% 0; }
-  100% { background-position: -200% 0; }
+  0% {
+    background-position: 200% 0;
+  }
+
+  100% {
+    background-position: -200% 0;
+  }
 }
 
 /* Section headers */
@@ -533,11 +1084,12 @@ body { background: var(--vscode-sideBar-background); }
   opacity: 0.8;
   margin-bottom: 5px;
 }
+
 .hs-ai-section-head::after {
   content: '';
   flex: 1;
   height: 1px;
-  background: var(--vscode-panel-border, rgba(128,128,128,0.14));
+  background: var(--vscode-panel-border, rgba(128, 128, 128, 0.14));
 }
 
 /* Checklist items */
@@ -551,15 +1103,41 @@ body { background: var(--vscode-sideBar-background); }
   cursor: pointer;
   animation: hs-row-in 0.18s ease both;
 }
-.hs-ai-item:hover { background: var(--vscode-list-hoverBackground); }
-.hs-ai-item:nth-child(1) { animation-delay: .05s; }
-.hs-ai-item:nth-child(2) { animation-delay: .09s; }
-.hs-ai-item:nth-child(3) { animation-delay: .13s; }
-.hs-ai-item:nth-child(4) { animation-delay: .17s; }
-.hs-ai-item:nth-child(5) { animation-delay: .21s; }
+
+.hs-ai-item:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
+.hs-ai-item:nth-child(1) {
+  animation-delay: .05s;
+}
+
+.hs-ai-item:nth-child(2) {
+  animation-delay: .09s;
+}
+
+.hs-ai-item:nth-child(3) {
+  animation-delay: .13s;
+}
+
+.hs-ai-item:nth-child(4) {
+  animation-delay: .17s;
+}
+
+.hs-ai-item:nth-child(5) {
+  animation-delay: .21s;
+}
+
 @keyframes hs-row-in {
-  from { opacity: 0; transform: translateX(-4px); }
-  to   { opacity: 1; transform: translateX(0); }
+  from {
+    opacity: 0;
+    transform: translateX(-4px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
 }
 
 /* Custom checkbox */
@@ -576,20 +1154,25 @@ body { background: var(--vscode-sideBar-background); }
   position: relative;
   transition: border-color 0.1s, background 0.1s;
 }
+
 .hs-ai-cb:checked {
   background: var(--vscode-button-background);
   border-color: var(--vscode-button-background);
 }
+
 .hs-ai-cb:checked::after {
   content: '';
   position: absolute;
-  left: 2px; top: -1px;
-  width: 5px; height: 8px;
+  left: 2px;
+  top: -1px;
+  width: 5px;
+  height: 8px;
   border: 1.5px solid var(--vscode-button-foreground);
   border-top: none;
   border-left: none;
   transform: rotate(45deg);
 }
+
 .hs-ai-cb:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
   outline-offset: 1px;
@@ -615,6 +1198,7 @@ body { background: var(--vscode-sideBar-background); }
   color: var(--vscode-descriptionForeground);
   white-space: nowrap;
 }
+
 .hs-ai-item-status::before {
   content: '';
   display: inline-block;
@@ -623,14 +1207,22 @@ body { background: var(--vscode-sideBar-background); }
   border-radius: 1px;
   flex-shrink: 0;
 }
-.hs-ai-item-status--ok::before   { background: #4ade80; }
-.hs-ai-item-status--none::before { background: rgba(255,255,255,0.15); }
+
+.hs-ai-item-status--ok::before {
+  background: #4ade80;
+}
+
+.hs-ai-item-status--none::before {
+  background: rgba(255, 255, 255, 0.15);
+}
+
 .hs-ai-platform-badge {
   font-size: 9px;
   font-weight: 400;
   color: var(--vscode-descriptionForeground);
   margin-left: 4px;
 }
+
 .hs-ai-platform-sub {
   display: block;
   font-size: 9px;
@@ -639,7 +1231,11 @@ body { background: var(--vscode-sideBar-background); }
   margin-top: 1px;
 }
 
-.hs-ai-item input[type="checkbox"]:disabled { opacity: 0.5; cursor: default; }
+.hs-ai-item input[type="checkbox"]:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
 .hs-ai-hint {
   font-size: 9px;
   color: var(--vscode-descriptionForeground);
@@ -656,14 +1252,28 @@ body { background: var(--vscode-sideBar-background); }
   align-items: center;
   justify-content: center;
   font-size: 9px;
-  animation: tick-in 0.2s cubic-bezier(0.34,1.56,0.64,1) both;
+  animation: tick-in 0.2s cubic-bezier(0.34, 1.56, 0.64, 1) both;
 }
+
 @keyframes tick-in {
-  from { opacity: 0; transform: scale(0); }
-  to   { opacity: 1; transform: scale(1); }
+  from {
+    opacity: 0;
+    transform: scale(0);
+  }
+
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.hs-ai-item-tick--ok {
+  color: #4ade80;
+}
+
+.hs-ai-item-tick--err {
+  color: var(--vscode-errorForeground);
 }
-.hs-ai-item-tick--ok  { color: #4ade80; }
-.hs-ai-item-tick--err { color: var(--vscode-errorForeground); }
 
 /* Apply button */
 .hs-ai-apply {
@@ -683,16 +1293,28 @@ body { background: var(--vscode-sideBar-background); }
   overflow: hidden;
   margin-top: 2px;
 }
+
 .hs-ai-apply::after {
   content: '';
   position: absolute;
   inset: 0;
-  background: rgba(255,255,255,0);
+  background: rgba(255, 255, 255, 0);
   transition: background 0.12s;
 }
-.hs-ai-apply:hover::after { background: rgba(255,255,255,0.08); }
-.hs-ai-apply:disabled { opacity: 0.35; cursor: default; }
-.hs-ai-apply:disabled::after { background: none; }
+
+.hs-ai-apply:hover::after {
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.hs-ai-apply:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+
+.hs-ai-apply:disabled::after {
+  background: none;
+}
+
 .hs-ai-apply:focus-visible {
   outline: 1px solid var(--vscode-focusBorder);
   outline-offset: 2px;
@@ -704,8 +1326,10 @@ body { background: var(--vscode-sideBar-background); }
   color: var(--vscode-errorForeground);
   padding: 5px 7px;
   border-radius: 4px;
-  background: rgba(241,76,76,0.08);
-  border: 1px solid rgba(241,76,76,0.2);
+  background: rgba(241, 76, 76, 0.08);
+  border: 1px solid rgba(241, 76, 76, 0.2);
 }
 
-.hidden { display: none !important; }
+.hidden {
+  display: none !important;
+}
diff --git a/media/styles/library.css b/media/styles/library.css
new file mode 100644
index 0000000..83a76b3
--- /dev/null
+++ b/media/styles/library.css
@@ -0,0 +1,833 @@
+/**
+ * Cloudinary Media Library — sidebar webview.
+ * Considered utility: precise rhythm, brand accents, VS Code-native.
+ */
+
+:root {
+  --lib-row-height: 22px;
+  --lib-slot: 18px;
+  --lib-accent: var(--vscode-textLink-foreground, var(--cld-sky-blue));
+  --lib-accent-soft: color-mix(in srgb, var(--lib-accent) 14%, transparent);
+  --lib-accent-softer: color-mix(in srgb, var(--lib-accent) 8%, transparent);
+  --lib-accent-strong: color-mix(in srgb, var(--lib-accent) 26%, transparent);
+  --lib-header-bg: var(--vscode-sideBarSectionHeader-background, var(--vscode-sideBar-background));
+  --lib-header-border: var(--vscode-sideBarSectionHeader-border, var(--vscode-widget-border, transparent));
+  --lib-icon-muted: var(--vscode-icon-foreground);
+}
+
+html,
+body {
+  height: 100vh;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  font-family: var(--vscode-font-family);
+  font-size: var(--vscode-font-size);
+  color: var(--vscode-sideBar-foreground, var(--vscode-foreground));
+  background: var(--vscode-sideBar-background);
+}
+
+/* ========================================
+   Header
+   ======================================== */
+.lib-header {
+  flex: 0 0 auto;
+  background: var(--lib-header-bg);
+  border-bottom: 1px solid var(--lib-header-border);
+}
+
+/* ========================================
+   Filter / sort bar
+   ======================================== */
+.lib-filter {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 8px 8px;
+  border-top: 1px solid var(--lib-header-border);
+  animation: libFilterIn 140ms ease-out;
+}
+
+@keyframes libFilterIn {
+  from { opacity: 0; transform: translateY(-2px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.lib-filter__group {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+  padding: 0 8px 0 10px;
+  height: 26px;
+  background: var(--vscode-input-background);
+  border: 1px solid var(--vscode-input-border, var(--vscode-widget-border, transparent));
+  border-radius: 5px;
+  cursor: pointer;
+  transition: border-color 140ms ease, box-shadow 140ms ease;
+}
+
+.lib-filter__group:focus-within {
+  border-color: var(--lib-accent);
+  box-shadow: 0 0 0 1px var(--lib-accent-soft);
+}
+
+.lib-filter__label {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--vscode-descriptionForeground);
+  flex-shrink: 0;
+}
+
+.lib-filter__select {
+  flex: 1;
+  min-width: 0;
+  background: transparent;
+  border: none;
+  outline: none;
+  color: var(--vscode-input-foreground, var(--vscode-foreground));
+  font-family: inherit;
+  font-size: var(--vscode-font-size);
+  cursor: pointer;
+  appearance: none;
+  padding: 0 14px 0 0;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='10' viewBox='0 0 10 10'%3E%3Cpath fill='%23999' d='M2 4l3 3 3-3'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 0 center;
+}
+
+.lib-filter__select::-ms-expand {
+  display: none;
+}
+
+/* ========================================
+   Search bar
+   ======================================== */
+.lib-search {
+  padding: 6px 8px 8px;
+  border-top: 1px solid var(--lib-header-border);
+  animation: libSearchIn 140ms ease-out;
+}
+
+@keyframes libSearchIn {
+  from { opacity: 0; transform: translateY(-2px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.lib-search__wrap {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 0 8px;
+  height: 26px;
+  background: var(--vscode-input-background);
+  color: var(--vscode-input-foreground);
+  border: 1px solid var(--vscode-input-border, var(--vscode-widget-border, transparent));
+  border-radius: 5px;
+  transition: border-color 140ms ease, box-shadow 140ms ease;
+  overflow: hidden;
+}
+
+.lib-search__wrap:focus-within {
+  border-color: var(--lib-accent);
+  box-shadow: 0 0 0 1px var(--lib-accent-soft);
+}
+
+.lib-search__icon {
+  flex-shrink: 0;
+  color: var(--vscode-input-placeholderForeground, var(--lib-icon-muted));
+  opacity: 0.85;
+}
+
+.lib-search__wrap:focus-within .lib-search__icon {
+  color: var(--lib-accent);
+  opacity: 1;
+}
+
+.lib-search__input {
+  flex: 1;
+  min-width: 0;
+  background: transparent;
+  border: none;
+  outline: none;
+  color: inherit;
+  font-family: inherit;
+  font-size: var(--vscode-font-size);
+  line-height: 1;
+  padding: 0;
+}
+
+.lib-search__input::placeholder {
+  color: var(--vscode-input-placeholderForeground);
+  opacity: 0.7;
+}
+
+.lib-search__clear {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  background: transparent;
+  border: none;
+  border-radius: 50%;
+  color: var(--vscode-descriptionForeground);
+  cursor: pointer;
+  font-size: 11px;
+  line-height: 1;
+  padding: 0;
+  transition: background-color 100ms ease, color 100ms ease;
+}
+
+.lib-search__clear:hover {
+  background: var(--vscode-toolbar-hoverBackground, rgba(90, 93, 94, 0.18));
+  color: var(--vscode-foreground);
+}
+
+.lib-search__loading {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  color: var(--vscode-progressBar-background, var(--lib-accent));
+}
+
+.lib-search__spinner {
+  width: 12px;
+  height: 12px;
+  border: 2px solid rgba(127, 127, 127, 0.35);
+  border-top-color: currentColor;
+  border-radius: 50%;
+  animation: libSearchSpin 720ms linear infinite;
+}
+
+.lib-search--loading .lib-search__clear {
+  display: none;
+}
+
+@keyframes libSearchSpin {
+  to { transform: rotate(360deg); }
+}
+
+/* ========================================
+   Error banner
+   ======================================== */
+.lib-error {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 12px;
+  background: var(--vscode-inputValidation-errorBackground);
+  color: var(--vscode-inputValidation-errorForeground, var(--vscode-foreground));
+  border-bottom: 1px solid var(--vscode-inputValidation-errorBorder);
+  font-size: var(--vscode-font-size);
+  flex: 0 0 auto;
+  animation: libErrorIn 180ms ease-out;
+}
+
+@keyframes libErrorIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.lib-error__dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--vscode-inputValidation-errorBorder, var(--cld-pink));
+  flex-shrink: 0;
+  animation: libErrorPulse 1.4s ease-in-out infinite;
+}
+
+@keyframes libErrorPulse {
+  0%, 100% { transform: scale(1); opacity: 1; }
+  50%      { transform: scale(1.3); opacity: 0.6; }
+}
+
+.lib-error__msg {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.lib-error__retry {
+  flex-shrink: 0;
+  background: transparent;
+  color: inherit;
+  border: 1px solid currentColor;
+  border-radius: 3px;
+  padding: 2px 10px;
+  font-family: inherit;
+  font-size: calc(var(--vscode-font-size) - 1px);
+  cursor: pointer;
+  opacity: 0.85;
+  transition: opacity 140ms ease, background-color 140ms ease;
+}
+
+.lib-error__retry:hover {
+  opacity: 1;
+  background: rgba(0, 0, 0, 0.08);
+}
+
+/* ========================================
+   List container
+   ======================================== */
+.lib-root {
+  flex: 1 1 auto;
+  position: relative;
+  overflow-y: auto;
+  overflow-x: hidden;
+  outline: none;
+  padding: 4px 0;
+}
+
+/* ========================================
+   Rows — 22px precision grid
+   ======================================== */
+.lib-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  height: var(--lib-row-height);
+  padding: 0 10px 0 4px;
+  box-sizing: border-box;
+  cursor: pointer;
+  user-select: none;
+  white-space: nowrap;
+  color: var(--vscode-sideBar-foreground, var(--vscode-foreground));
+  position: relative;
+}
+
+.lib-row::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 2px;
+  bottom: 2px;
+  width: 2px;
+  border-radius: 0 2px 2px 0;
+  background: transparent;
+  transition: background-color 120ms ease;
+}
+
+.lib-row:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
+.lib-row--selected,
+.lib-row--selected:hover {
+  background: var(--vscode-list-activeSelectionBackground);
+  color: var(--vscode-list-activeSelectionForeground);
+}
+
+.lib-row--selected::before {
+  background: var(--lib-accent);
+}
+
+.lib-root:focus-within .lib-row--selected {
+  background: var(--vscode-list-focusBackground, var(--vscode-list-activeSelectionBackground));
+}
+
+.lib-indent {
+  display: inline-block;
+  flex: 0 0 auto;
+  height: 1px;
+}
+
+/* Fixed-width slots for perfect alignment */
+.lib-twistie,
+.lib-twistie-spacer,
+.lib-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--lib-slot);
+  height: var(--lib-row-height);
+  flex: 0 0 var(--lib-slot);
+}
+
+.lib-twistie {
+  color: var(--lib-icon-muted);
+  cursor: pointer;
+  opacity: 0.75;
+}
+
+.lib-twistie svg {
+  display: block;
+  transition: transform 140ms cubic-bezier(0.2, 0.8, 0.2, 1);
+  transform-origin: 50% 50%;
+}
+
+.lib-twistie--open svg {
+  transform: rotate(90deg);
+}
+
+.lib-row--folder:hover .lib-twistie {
+  opacity: 1;
+}
+
+/* Icon colors — semantic per type */
+.lib-icon {
+  color: var(--lib-icon-muted);
+}
+
+.lib-icon svg {
+  display: block;
+}
+
+.lib-icon--folder {
+  color: color-mix(in srgb, var(--lib-accent) 75%, var(--lib-icon-muted));
+}
+
+.lib-row--folder-open .lib-icon--folder {
+  color: var(--lib-accent);
+}
+
+.lib-row--selected .lib-twistie,
+.lib-row--selected .lib-icon,
+.lib-row--selected .lib-icon--folder {
+  color: var(--vscode-list-activeSelectionForeground);
+}
+
+.lib-row--image .lib-icon--asset {
+  color: color-mix(in srgb, var(--cld-teal) 60%, var(--lib-icon-muted));
+}
+
+.lib-row--video .lib-icon--asset {
+  color: color-mix(in srgb, var(--cld-pink) 55%, var(--lib-icon-muted));
+}
+
+.lib-row--raw .lib-icon--asset {
+  color: var(--lib-icon-muted);
+  opacity: 0.7;
+}
+
+.lib-row--authenticated .lib-icon--asset {
+  color: color-mix(in srgb, var(--vscode-charts-yellow, #cca700) 65%, var(--lib-icon-muted));
+}
+
+/* Name */
+.lib-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: var(--vscode-font-size);
+  line-height: normal;
+  letter-spacing: 0.01em;
+}
+
+.lib-row--folder .lib-name {
+  font-weight: 500;
+}
+
+.lib-row--folder-open .lib-name {
+  color: var(--vscode-foreground);
+}
+
+.lib-auth-lock {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 12px;
+  width: 12px;
+  height: var(--lib-row-height);
+  color: var(--vscode-charts-yellow, #cca700);
+  opacity: 0.9;
+}
+
+.lib-auth-lock svg {
+  display: block;
+}
+
+/* Asset metadata — format · size, right-aligned */
+.lib-meta {
+  flex: 0 0 auto;
+  margin-left: 6px;
+  font-size: calc(var(--vscode-font-size) - 1.5px);
+  color: var(--vscode-descriptionForeground);
+  letter-spacing: 0.02em;
+  line-height: normal;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  opacity: 0.85;
+  transition: opacity 100ms ease;
+}
+
+.lib-row:hover .lib-meta,
+.lib-row--selected .lib-meta {
+  opacity: 1;
+}
+
+.lib-row--selected .lib-meta {
+  color: inherit;
+}
+
+.lib-row--selected .lib-auth-lock,
+.lib-row--selected.lib-row--authenticated .lib-icon--asset {
+  color: inherit;
+}
+
+/* Loading row */
+.lib-row--loading {
+  cursor: default;
+  color: var(--vscode-descriptionForeground);
+  font-style: italic;
+}
+
+.lib-row--loading:hover {
+  background: transparent;
+}
+
+.lib-row--search-loading {
+  color: var(--vscode-descriptionForeground);
+  font-style: normal;
+  background: transparent;
+}
+
+.lib-row--search-loading:hover {
+  background: transparent;
+}
+
+.lib-loader-dots {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  width: var(--lib-slot);
+  height: var(--lib-row-height);
+  justify-content: center;
+  flex: 0 0 var(--lib-slot);
+}
+
+.lib-loader-dots i {
+  width: 3px;
+  height: 3px;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.3;
+  animation: libDot 1.2s infinite ease-in-out;
+}
+
+.lib-loader-dots i:nth-child(2) { animation-delay: 0.15s; }
+.lib-loader-dots i:nth-child(3) { animation-delay: 0.3s; }
+
+@keyframes libDot {
+  0%, 100% { opacity: 0.25; transform: scale(0.8); }
+  50%      { opacity: 1;    transform: scale(1); }
+}
+
+/* Clear-search chip row */
+.lib-row--clear {
+  padding: 0 10px 0 4px;
+}
+
+.lib-row--clear::before {
+  display: none;
+}
+
+.lib-row--clear:hover {
+  background: transparent;
+}
+
+.lib-clear-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  height: 16px;
+  padding: 0 8px 0 6px;
+  border-radius: 10px;
+  background: var(--vscode-badge-background);
+  color: var(--vscode-badge-foreground);
+  font-size: calc(var(--vscode-font-size) - 1px);
+  font-weight: 500;
+  max-width: calc(100% - 12px);
+  transition:
+    background-color 140ms ease,
+    color 140ms ease,
+    transform 140ms ease;
+}
+
+.lib-row--clear:hover .lib-clear-chip {
+  background: var(--lib-accent);
+  color: var(--vscode-editor-background);
+  transform: translateX(1px);
+}
+
+.lib-clear-chip__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 10px;
+  height: 10px;
+}
+
+.lib-clear-chip__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ========================================
+   Context menu
+   ======================================== */
+.lib-menu {
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: 6px;
+  min-width: 200px;
+  max-width: 260px;
+  background: var(--vscode-menu-background, var(--vscode-editorWidget-background));
+  color: var(--vscode-menu-foreground, var(--vscode-foreground));
+  border: 1px solid var(--vscode-menu-border, var(--vscode-widget-border, transparent));
+  border-radius: 7px;
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.16),
+    0 10px 28px rgba(0, 0, 0, 0.32);
+  font-size: calc(var(--vscode-font-size) - 0.5px);
+  z-index: 1000;
+  overflow: hidden;
+  animation: libMenuIn 130ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+
+.lib-menu::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 1px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    var(--lib-accent-soft) 28%,
+    var(--lib-accent-soft) 72%,
+    transparent 100%
+  );
+  pointer-events: none;
+}
+
+@keyframes libMenuIn {
+  from { opacity: 0; transform: translateY(-3px) scale(0.97); }
+  to   { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+.lib-menu-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 7px 12px 7px 11px;
+  background: transparent;
+  border: none;
+  border-radius: 5px;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  position: relative;
+  white-space: nowrap;
+  transition:
+    background-color 100ms ease,
+    color 100ms ease,
+    transform 100ms ease;
+}
+
+.lib-menu-item::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 5px;
+  bottom: 5px;
+  width: 2px;
+  border-radius: 0 2px 2px 0;
+  background: transparent;
+  transition: background-color 100ms ease;
+}
+
+.lib-menu-item__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  flex: 0 0 14px;
+  color: var(--lib-icon-muted);
+  opacity: 0.85;
+  transition: color 100ms ease, opacity 100ms ease;
+}
+
+.lib-menu-item__icon svg {
+  display: block;
+  width: 14px;
+  height: 14px;
+}
+
+.lib-menu-item__label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  letter-spacing: 0.01em;
+}
+
+.lib-menu-item:hover,
+.lib-menu-item--active {
+  background: var(--vscode-menu-selectionBackground, var(--vscode-list-activeSelectionBackground));
+  color: var(--vscode-menu-selectionForeground, var(--vscode-list-activeSelectionForeground));
+}
+
+.lib-menu-item:hover::before,
+.lib-menu-item--active::before {
+  background: var(--lib-accent);
+}
+
+.lib-menu-item:hover .lib-menu-item__icon,
+.lib-menu-item--active .lib-menu-item__icon {
+  color: inherit;
+  opacity: 1;
+}
+
+.lib-menu-item:active {
+  transform: scale(0.99);
+}
+
+.lib-menu-item:focus-visible {
+  outline: none;
+}
+
+.lib-menu__divider {
+  height: 1px;
+  margin: 4px 6px;
+  background: var(--vscode-menu-separatorBackground, var(--vscode-widget-border, currentColor));
+  opacity: 0.35;
+}
+
+/* ========================================
+   Empty state
+   ======================================== */
+.lib-empty {
+  padding: 24px 16px;
+  color: var(--vscode-descriptionForeground);
+  text-align: center;
+  font-size: var(--vscode-font-size);
+  flex: 0 0 auto;
+}
+
+.lib-empty--welcome {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  margin: 18px 14px;
+  padding: 22px 18px 20px;
+  background: var(--vscode-editorWidget-background, var(--vscode-editor-background));
+  border: 1px solid var(--vscode-widget-border, transparent);
+  border-radius: 10px;
+  position: relative;
+  overflow: hidden;
+}
+
+.lib-empty--welcome::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: linear-gradient(
+    90deg,
+    var(--cld-brand-blue) 0%,
+    var(--cld-sky-blue) 55%,
+    var(--cld-turquoise) 100%
+  );
+}
+
+.lib-empty__glyph {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 38px;
+  height: 38px;
+  border-radius: 10px;
+  background: var(--lib-accent-soft);
+  color: var(--lib-accent);
+}
+
+.lib-empty__glyph svg {
+  width: 20px;
+  height: 20px;
+}
+
+.lib-empty__title {
+  margin: 0;
+  font-size: var(--vscode-font-size);
+  line-height: 1.45;
+  color: var(--vscode-foreground);
+}
+
+.lib-empty__cta {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 5px 14px;
+  border: none;
+  border-radius: 4px;
+  background: var(--vscode-button-background);
+  color: var(--vscode-button-foreground);
+  font-family: inherit;
+  font-size: var(--vscode-font-size);
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color 140ms ease, transform 140ms ease;
+}
+
+.lib-empty__cta:hover {
+  background: var(--vscode-button-hoverBackground);
+  transform: translateY(-0.5px);
+}
+
+.lib-empty__cta:focus-visible {
+  outline: 1.5px solid var(--lib-accent);
+  outline-offset: 2px;
+}
+
+/* ========================================
+   Reduced motion
+   ======================================== */
+@media (prefers-reduced-motion: reduce) {
+  .lib-twistie svg,
+  .lib-row::before,
+  .lib-loader-dots i,
+  .lib-error,
+  .lib-error__dot,
+  .lib-search,
+  .lib-search__wrap,
+  .lib-search__spinner,
+  .lib-filter,
+  .lib-filter__group,
+  .lib-menu,
+  .lib-menu-item,
+  .lib-menu-item__icon,
+  .lib-clear-chip,
+  .lib-empty__cta {
+    transition: none;
+    animation: none;
+  }
+}
diff --git a/package-lock.json b/package-lock.json
index 507d030..faead14 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "cloudinary",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cloudinary",
-      "version": "0.1.2",
+      "version": "1.0.0",
       "license": "MIT",
       "dependencies": {
         "cloudinary": "^2.5.1"
@@ -21,6 +21,8 @@
         "esbuild": "^0.25.9",
         "eslint": "^8.52.0",
         "glob": "^10.3.10",
+        "highlight.js": "^11.11.1",
+        "marked": "^17.0.3",
         "mocha": "^10.2.0",
         "npm-run-all": "^4.1.5",
         "typescript": "^5.2.2"
@@ -738,6 +740,7 @@
       "integrity": "sha512-pUXGCuHnnKw6PyYq93lLRiZm3vjuslIy7tus1lIQTYVK9bL8XBgJnCWm8a0KcTtHC84Yya1Q6rtll+duSMj0dg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.39.1",
         "@typescript-eslint/types": "8.39.1",
@@ -993,6 +996,7 @@
       "integrity": "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -1952,6 +1956,7 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -2619,6 +2624,16 @@
         "he": "bin/he"
       }
     },
+    "node_modules/highlight.js": {
+      "version": "11.11.1",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.11.1.tgz",
+      "integrity": "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/hosted-git-info": {
       "version": "2.8.9",
       "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.9.tgz",
@@ -3400,6 +3415,19 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/marked": {
+      "version": "17.0.3",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.3.tgz",
+      "integrity": "sha512-jt1v2ObpyOKR8p4XaUJVk3YWRJ5n+i4+rjQopxvV32rSndTJXvIzuUdWWIy/1pFQMkQmvTXawzDNqOH/CUmx6A==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -5242,6 +5270,7 @@
       "integrity": "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
diff --git a/package.json b/package.json
index d1e3ff7..4212e45 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
   "publisher": "Cloudinary",
   "displayName": "Cloudinary",
   "description": "Easily find and manage your Cloudinary assets directly from Visual Studio Code.",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "icon": "resources/cloudinary_icon_blue.png",
   "repository": {
     "type": "git",
@@ -53,15 +53,35 @@
           "id": "cloudinaryHomescreen",
           "name": "Cloudinary",
           "type": "webview",
-          "when": "cloudinary.activeView != 'library'"
+          "when": "cloudinary.activeView != 'library' && cloudinary.activeView != 'docsAi'"
         },
         {
           "id": "cloudinaryMediaLibrary",
-          "name": "",
+          "name": "Library",
+          "type": "webview",
+          "contextualTitle": "Cloudinary Library",
           "when": "cloudinary.activeView == 'library'"
+        },
+        {
+          "id": "cloudinaryDocsAI",
+          "name": "Docs AI",
+          "type": "webview",
+          "contextualTitle": "Cloudinary Docs AI",
+          "when": "cloudinary.activeView == 'docsAi'"
         }
       ]
     },
+    "configuration": {
+      "title": "Cloudinary",
+      "properties": {
+        "cloudinary.docsAi.apiBase": {
+          "type": "string",
+          "default": "https://cld-docs-ai-delta.vercel.app",
+          "scope": "machine-overridable",
+          "markdownDescription": "Base URL for the Cloudinary Docs AI backend. Override this for local development, for example `http://127.0.0.1:5173`."
+        }
+      }
+    },
     "commands": [
       {
         "command": "cloudinary.openAsset",
@@ -131,65 +151,29 @@
         "title": "Browse Media Library",
         "category": "Cloudinary"
       },
+      {
+        "command": "cloudinary.showDocsAI",
+        "title": "Open Docs AI",
+        "category": "Cloudinary"
+      },
       {
         "command": "cloudinary.configureAiTools",
         "title": "Configure AI Tools",
         "category": "Cloudinary"
+      },
+      {
+        "command": "cloudinary.docsAi.refresh",
+        "title": "Refresh Docs AI",
+        "icon": "$(refresh)",
+        "category": "Cloudinary"
+      },
+      {
+        "command": "cloudinary.refreshFolderMode",
+        "title": "Refresh Folder Mode",
+        "icon": "$(refresh)",
+        "category": "Cloudinary"
       }
-    ],
-    "menus": {
-      "view/title": [
-        {
-          "command": "cloudinary.showHomescreen",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@0"
-        },
-        {
-          "command": "cloudinary.refresh",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@1"
-        },
-        {
-          "command": "cloudinary.openUploadWidget",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@2"
-        },
-        {
-          "command": "cloudinary.searchAssets",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@3"
-        },
-        {
-          "command": "cloudinary.viewOptions",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@4"
-        },
-        {
-          "command": "cloudinary.openGlobalConfig",
-          "when": "view == cloudinaryMediaLibrary",
-          "group": "navigation@5"
-        }
-      ],
-      "view/item/context": [
-        {
-          "command": "cloudinary.copyUrl",
-          "when": "view == cloudinaryMediaLibrary && viewItem == 'asset'"
-        },
-        {
-          "command": "cloudinary.copyPublicId",
-          "when": "view == cloudinaryMediaLibrary && viewItem == 'asset'"
-        },
-        {
-          "command": "cloudinary.copyOptimizedUrl",
-          "when": "view == cloudinaryMediaLibrary && viewItem == 'asset'"
-        },
-        {
-          "command": "cloudinary.uploadToFolder",
-          "when": "view == cloudinaryMediaLibrary && viewItem == 'folder'",
-          "group": "inline"
-        }
-      ]
-    }
+    ]
   },
   "scripts": {
     "compile": "npm run check-types && node esbuild.js",
@@ -215,6 +199,8 @@
     "esbuild": "^0.25.9",
     "eslint": "^8.52.0",
     "glob": "^10.3.10",
+    "highlight.js": "^11.11.1",
+    "marked": "^17.0.3",
     "mocha": "^10.2.0",
     "npm-run-all": "^4.1.5",
     "typescript": "^5.2.2"
diff --git a/src/aiToolsService.ts b/src/aiToolsService.ts
index 3e0adb7..80dedbb 100644
--- a/src/aiToolsService.ts
+++ b/src/aiToolsService.ts
@@ -58,22 +58,37 @@ export function detectEditor(): EditorType {
 
 export function getMcpFilePath(editor: EditorType): string {
   switch (editor) {
-    case "cursor":      return ".cursor/mcp.json";
-    case "windsurf":    return ".windsurf/mcp.json";
+    case "cursor": return ".cursor/mcp.json";
+    case "windsurf": return ".windsurf/mcp.json";
     case "antigravity": return ".agent/mcp_config.json";
     case "vscode":
-    default:            return ".vscode/mcp.json";
+    default: return ".vscode/mcp.json";
   }
 }
 
+export function getMcpRootKey(editor: EditorType): "servers" | "mcpServers" {
+  return editor === "vscode" ? "servers" : "mcpServers";
+}
+
+export function getEditorDisplayName(editor: EditorType): string | undefined {
+  const names: Partial<Record<EditorType, string>> = {
+    vscode: "VS Code", cursor: "Cursor", windsurf: "Windsurf", antigravity: "Antigravity",
+  };
+  return names[editor];
+}
+
+function stripTilde(dir: string): string {
+  return dir.replace(/^~\/?/, "");
+}
+
 export function detectEditorPlatform(): string {
   const editor = detectEditor();
   switch (editor) {
-    case "cursor":      return "cursor";
-    case "windsurf":    return "windsurf";
+    case "cursor": return "cursor";
+    case "windsurf": return "windsurf";
     case "antigravity": return "antigravity";
     case "vscode":
-    default:            return "github-copilot";
+    default: return "github-copilot";
   }
 }
 
@@ -408,7 +423,7 @@ export async function installSkill(
 ): Promise<void> {
   const base = scope === "global" ? os.homedir() : rootUri.fsPath;
   const rawDir = scope === "global" ? platform.globalSkillsDir : platform.skillsDir;
-  const dir = scope === "global" ? rawDir.replace(/^~\/?/, "") : rawDir;
+  const dir = scope === "global" ? stripTilde(rawDir) : rawDir;
 
   // Write SKILL.md (silent overwrite — matches `npx skills add -y` behaviour)
   const skillPath = path.join(dir, dirName, "SKILL.md");
@@ -466,7 +481,7 @@ export async function readInstalledSkillDirNames(
   }
 
   const projectDir = platform.skillsDir;
-  const globalDir = platform.globalSkillsDir.replace(/^~\/?/, "");
+  const globalDir = stripTilde(platform.globalSkillsDir);
 
   const [project, global] = await Promise.all([
     checkScope(projectBase, projectDir),
@@ -546,8 +561,7 @@ export async function installMcpServers(
   createdFiles: string[]
 ): Promise<void> {
   const mcpFilePath = getMcpFilePath(editor);
-  const isVscode = editor === "vscode";
-  const rootKey = isVscode ? "servers" : "mcpServers";
+  const rootKey = getMcpRootKey(editor);
   const mcpUri = vscode.Uri.joinPath(rootUri, mcpFilePath);
   let config: Record<string, unknown> = {};
   try {
diff --git a/src/analytics/analyticsService.ts b/src/analytics/analyticsService.ts
new file mode 100644
index 0000000..4c075f3
--- /dev/null
+++ b/src/analytics/analyticsService.ts
@@ -0,0 +1,187 @@
+import { randomUUID } from "crypto";
+
+export type AnalyticsValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined;
+
+export type AnalyticsPayload = Record<string, unknown>;
+
+type AnalyticsStorage = {
+  get<T>(key: string, defaultValue: T): T;
+  update(key: string, value: unknown): Thenable<void>;
+};
+
+type AnalyticsServiceOptions = {
+  extensionVersion: string;
+  storage: AnalyticsStorage;
+  getCloudName?: () => string | null | undefined;
+  getDebugId?: () => string | null | undefined;
+  getIdePlatform?: () => string;
+  fetchFn?: (url: string, init: { method: "POST" }) => Promise<unknown>;
+  now?: () => Date;
+  createSessionId?: () => string;
+};
+
+const ANALYTICS_ENDPOINT = "https://analytics-api.cloudinary.com";
+const ANALYTICS_FEATURE = "vscode_extension";
+// Parentheses and spaces are invalid in Cloudinary cloud names, so this
+// sentinel can never collide with a real configured cloud.
+const NO_CLOUD_CONFIGURED = "(not configured)";
+const SESSION_STORAGE_KEY = "cloudinary.analyticsSessionId";
+const SENSITIVE_PAYLOAD_KEYS = new Set([
+  "apikey",
+  "api_key",
+  "apisecret",
+  "api_secret",
+  "accesstoken",
+  "access_token",
+  "authorization",
+  "clientsecret",
+  "client_secret",
+  "email",
+  "idtoken",
+  "id_token",
+  "message",
+  "message_content",
+  "password",
+  "phone",
+  "prompt",
+  "refreshtoken",
+  "refresh_token",
+  "secret",
+  "token",
+  "useremail",
+  "user_email",
+  "user_message",
+]);
+const RESERVED_PAYLOAD_KEYS = new Set([
+  "source",
+  "extension_version",
+  "ide_platform",
+  "session_id",
+  "event_time",
+  "event",
+]);
+
+function isSafeEventName(eventName: string): boolean {
+  return /^[a-z][a-z0-9_]*$/.test(eventName);
+}
+
+function normalizePayloadKey(key: string): string {
+  return key.trim().replace(/[-.\s]/g, "_").toLowerCase();
+}
+
+function normalizePayloadValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  }
+
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : undefined;
+  }
+
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+
+  return undefined;
+}
+
+function isSensitivePayloadKey(key: string): boolean {
+  const normalizedKey = normalizePayloadKey(key);
+  return SENSITIVE_PAYLOAD_KEYS.has(normalizedKey);
+}
+
+function isReservedPayloadKey(key: string): boolean {
+  return RESERVED_PAYLOAD_KEYS.has(normalizePayloadKey(key));
+}
+
+export class AnalyticsService {
+  private readonly extensionVersion: string;
+  private readonly storage: AnalyticsStorage;
+  private readonly getCloudName: () => string | null | undefined;
+  private readonly getDebugId: () => string | null | undefined;
+  private readonly getIdePlatform: () => string;
+  private readonly fetchFn: (url: string, init: { method: "POST" }) => Promise<unknown>;
+  private readonly now: () => Date;
+  private readonly createSessionId: () => string;
+
+  constructor(options: AnalyticsServiceOptions) {
+    this.extensionVersion = options.extensionVersion;
+    this.storage = options.storage;
+    this.getCloudName = options.getCloudName ?? (() => undefined);
+    this.getDebugId = options.getDebugId ?? (() => undefined);
+    this.getIdePlatform = options.getIdePlatform ?? (() => "unknown");
+    this.fetchFn = options.fetchFn ?? ((url, init) => fetch(url, init));
+    this.now = options.now ?? (() => new Date());
+    this.createSessionId = options.createSessionId ?? randomUUID;
+  }
+
+  track(eventName: string, payload: AnalyticsPayload = {}): void {
+    void this.send(eventName, payload);
+  }
+
+  async send(eventName: string, payload: AnalyticsPayload = {}): Promise<void> {
+    if (!isSafeEventName(eventName)) {
+      return;
+    }
+
+    const sessionId = await this.getSessionId();
+    const cloudName = normalizePayloadValue(this.getCloudName());
+    const debugId = normalizePayloadValue(this.getDebugId());
+    const params = new URLSearchParams({
+      source: ANALYTICS_FEATURE,
+      event: eventName,
+      extension_version: this.extensionVersion,
+      ide_platform: this.getIdePlatform(),
+      session_id: sessionId,
+      event_time: this.now().toISOString(),
+    });
+
+    // Always attribute the event to the active cloud, falling back to an
+    // explicit sentinel so "no cloud configured" is distinguishable from a
+    // dropped param downstream.
+    params.set("cloud_name", cloudName ?? NO_CLOUD_CONFIGURED);
+    if (debugId) {
+      params.set("debug_id", debugId);
+    }
+
+    for (const [key, value] of Object.entries(payload)) {
+      if (!key || isReservedPayloadKey(key) || isSensitivePayloadKey(key)) {
+        continue;
+      }
+
+      const normalized = normalizePayloadValue(value);
+      if (normalized !== undefined) {
+        params.set(key, normalized);
+      }
+    }
+
+    const url = `${ANALYTICS_ENDPOINT}/${ANALYTICS_FEATURE}?${params.toString()}`;
+
+    try {
+      await this.fetchFn(url, { method: "POST" });
+    } catch {
+      // Analytics must never interrupt extension workflows.
+    }
+  }
+
+  private async getSessionId(): Promise<string> {
+    const existing = this.storage.get<string>(SESSION_STORAGE_KEY, "");
+    if (existing) {
+      return existing;
+    }
+
+    const created = this.createSessionId();
+    await this.storage.update(SESSION_STORAGE_KEY, created);
+    return created;
+  }
+}
diff --git a/src/analytics/trackConfigValidation.ts b/src/analytics/trackConfigValidation.ts
new file mode 100644
index 0000000..0d16558
--- /dev/null
+++ b/src/analytics/trackConfigValidation.ts
@@ -0,0 +1,39 @@
+import { AnalyticsService } from "./analyticsService";
+import type { FolderModeResult } from "../config/detectFolderMode";
+
+/**
+ * Emits a config validation analytics event based on a folder-mode detection result.
+ * Fires `config_validation_succeeded` when the credentials were accepted, or
+ * `config_validation_failed` when they were rejected or unreachable. `skipped`
+ * outcomes (missing or placeholder credentials) emit nothing.
+ *
+ * The payload never includes credentials; only the active cloud name (attached by
+ * the analytics service), the folder mode, and a coarse error reason are reported.
+ *
+ * @param analytics - The analytics service, if available.
+ * @param result - The folder-mode detection result.
+ * @param entryPoint - Where validation was triggered (activation, config_change, switch).
+ */
+export function trackConfigValidation(
+  analytics: AnalyticsService | undefined,
+  result: FolderModeResult,
+  entryPoint: string
+): void {
+  if (!analytics || result.outcome === "skipped") {
+    return;
+  }
+
+  if (result.outcome === "success") {
+    analytics.track("config_validation_succeeded", {
+      folder_mode: result.dynamicFolders ? "dynamic" : "fixed",
+      entry_point: entryPoint,
+    });
+    return;
+  }
+
+  analytics.track("config_validation_failed", {
+    error_reason: result.errorReason,
+    status: result.status,
+    entry_point: entryPoint,
+  });
+}
diff --git a/src/cloudinary/cloudinarySdkAdapter.ts b/src/cloudinary/cloudinarySdkAdapter.ts
new file mode 100644
index 0000000..dc180b3
--- /dev/null
+++ b/src/cloudinary/cloudinarySdkAdapter.ts
@@ -0,0 +1,46 @@
+import { v2 as cloudinary } from 'cloudinary';
+import { CloudinarySdkAdapter } from './cloudinaryService';
+import { SortDirection } from './types';
+
+/**
+ * Production adapter wired to the real Cloudinary SDK.
+ */
+export function createCloudinarySdkAdapter(): CloudinarySdkAdapter {
+  return {
+    subFolders: async (path: string) => {
+      return cloudinary.api.sub_folders(path) as unknown as {
+        folders: Array<{ name: string; path: string }>;
+      };
+    },
+    search: async (opts) => {
+      const query = cloudinary.search
+        .expression(opts.expression)
+        .sort_by(opts.sortBy.field, opts.sortBy.direction as SortDirection)
+        .max_results(opts.maxResults);
+
+      if (opts.withField) {
+        query.with_field(opts.withField);
+      }
+
+      if (opts.nextCursor) {
+        query.next_cursor(opts.nextCursor);
+      }
+
+      const result = await query.execute();
+      return {
+        resources: result.resources || [],
+        next_cursor: result.next_cursor || null,
+      };
+    },
+    uploadPresets: async () => {
+      return cloudinary.api.upload_presets({ max_results: 500 }) as unknown as {
+        presets: Array<{
+          name: string;
+          unsigned: boolean;
+          settings?: Record<string, unknown>;
+        }>;
+      };
+    },
+    urlFor: (publicId, opts) => cloudinary.url(publicId, opts as any),
+  };
+}
diff --git a/src/cloudinary/cloudinaryService.ts b/src/cloudinary/cloudinaryService.ts
new file mode 100644
index 0000000..709edc3
--- /dev/null
+++ b/src/cloudinary/cloudinaryService.ts
@@ -0,0 +1,297 @@
+import {
+  ChildrenPage,
+  ClientAsset,
+  ClientFolder,
+  FetchChildrenOpts,
+  SortDirection,
+  UploadPreset,
+} from './types';
+
+/**
+ * Narrow view of the Cloudinary SDK used by the service. Injecting this makes
+ * the service testable without loading the real SDK.
+ */
+export interface CloudinarySdkAdapter {
+  subFolders(path: string): Promise<{ folders: Array<{ name: string; path: string }> }>;
+  search(opts: {
+    expression: string;
+    sortBy: { field: string; direction: SortDirection };
+    maxResults: number;
+    nextCursor?: string;
+    withField?: string[];
+  }): Promise<{ resources: any[]; next_cursor: string | null }>;
+  uploadPresets(): Promise<{ presets: Array<{ name: string; unsigned: boolean; settings?: Record<string, unknown> }> }>;
+  urlFor(publicId: string, opts: {
+    resource_type: string;
+    type?: string;
+    transformation?: unknown;
+    sign_url?: boolean;
+    secure?: boolean;
+    format?: string;
+  }): string;
+}
+
+export interface Credentials {
+  cloudName: string | null;
+  apiKey: string | null;
+  apiSecret: string | null;
+  uploadPreset?: string | null;
+  dynamicFolders?: boolean;
+}
+
+/**
+ * Pure data layer for the Cloudinary media library.
+ * No vscode.* imports. All methods return plain JSON.
+ */
+export class CloudinaryService {
+  cloudName: string | null = null;
+  apiKey: string | null = null;
+  apiSecret: string | null = null;
+  uploadPreset: string | null = null;
+  dynamicFolders = false;
+  uploadPresets: UploadPreset[] = [];
+  /**
+   * Whether the configured credentials have been confirmed valid against the API.
+   * `true` = validated OK, `false` = rejected (e.g. 401/403), `undefined` = not
+   * yet checked. Drives the "Connected" vs "Setup needed" status, so it must not
+   * read `true` purely because credential fields are non-empty.
+   */
+  credentialsValid: boolean | undefined = undefined;
+
+  constructor(private readonly sdk: CloudinarySdkAdapter) {}
+
+  setCredentials(creds: Credentials): void {
+    this.cloudName = creds.cloudName;
+    this.apiKey = creds.apiKey;
+    this.apiSecret = creds.apiSecret;
+    this.uploadPreset = creds.uploadPreset ?? null;
+    this.dynamicFolders = creds.dynamicFolders ?? false;
+  }
+
+  async fetchChildren(folderPath: string, opts: FetchChildrenOpts): Promise<ChildrenPage> {
+    const expression = this.buildExpression(folderPath);
+    const [foldersResult, assetsResult] = await Promise.all([
+      this.sdk.subFolders(folderPath),
+      this.sdk.search({
+        expression,
+        sortBy: { field: 'created_at', direction: opts.sortDirection },
+        maxResults: 500,
+        nextCursor: opts.nextCursor,
+        withField: ['tags', 'context', 'metadata'],
+      }),
+    ]);
+
+    const folders: ClientFolder[] = (foldersResult.folders || []).map((f) => ({
+      name: f.name,
+      path: f.path,
+    }));
+
+    const filtered = (assetsResult.resources || []).filter((asset: any) => {
+      if (!this.dynamicFolders && folderPath === '' && typeof asset.public_id === 'string' && asset.public_id.includes('/')) {
+        return false;
+      }
+      if (opts.resourceTypeFilter === 'all') { return true; }
+      return String(asset.resource_type).toLowerCase() === opts.resourceTypeFilter;
+    });
+
+    const assets: ClientAsset[] = filtered.map((a: any) => this.toClientAsset(a));
+
+    return { folders, assets, nextCursor: assetsResult.next_cursor ?? null };
+  }
+
+  private buildExpression(folderPath: string): string {
+    if (this.dynamicFolders) {
+      return folderPath ? `asset_folder="${folderPath}"` : 'asset_folder=""';
+    }
+    // Fixed-folder root: empty expression returns ALL resources. fetchChildren
+    // then filters nested assets client-side. See the `public_id.includes('/')`
+    // guard in the resource filter.
+    return folderPath ? `folder="${folderPath}"` : '';
+  }
+
+  /**
+   * Streams remaining pages for a folder via callback. Caller can append to its
+   * own cache / forward over postMessage per batch. Stops when cursor is null
+   * or `cap` filtered assets have been delivered.
+   *
+   * NOTE: `cap` counts post-filter assets delivered to `onBatch`, not raw
+   * server resources. In fixed-folder-root mode with heavy client-side
+   * filtering, the actual API call volume may exceed `cap`.
+   */
+  async prefetchRemaining(
+    folderPath: string,
+    startCursor: string,
+    opts: FetchChildrenOpts,
+    onBatch: (assets: ClientAsset[], hasMore: boolean) => void,
+    cap: number = 5000,
+  ): Promise<void> {
+    let cursor: string | null = startCursor;
+    let total = 0;
+    const expression = this.buildExpression(folderPath);
+    while (cursor && total < cap) {
+      const result: { resources: any[]; next_cursor: string | null } = await this.sdk.search({
+        expression,
+        sortBy: { field: 'created_at', direction: opts.sortDirection },
+        maxResults: 500,
+        nextCursor: cursor,
+        withField: ['tags', 'context', 'metadata'],
+      });
+      const filtered = (result.resources || []).filter((asset: any) => {
+        if (!this.dynamicFolders && folderPath === '' && typeof asset.public_id === 'string' && asset.public_id.includes('/')) {
+          return false;
+        }
+        if (opts.resourceTypeFilter === 'all') { return true; }
+        return String(asset.resource_type).toLowerCase() === opts.resourceTypeFilter;
+      });
+      const assets = filtered.map((a: any) => this.toClientAsset(a));
+      cursor = result.next_cursor ?? null;
+      if (assets.length === 0) { continue; }
+      total += assets.length;
+      onBatch(assets, !!cursor && total < cap);
+    }
+  }
+
+  async searchAssets(query: string, opts: FetchChildrenOpts): Promise<{ assets: ClientAsset[]; nextCursor: string | null }> {
+    const result = await this.sdk.search({
+      expression: `${query}*`,
+      sortBy: { field: 'created_at', direction: opts.sortDirection },
+      maxResults: 500,
+      withField: ['tags', 'context', 'metadata'],
+    });
+    const assets = this.filterByResourceType(result.resources || [], opts.resourceTypeFilter)
+      .map((a: any) => this.toClientAsset(a));
+    return { assets, nextCursor: result.next_cursor ?? null };
+  }
+
+  async prefetchSearchResults(
+    query: string,
+    startCursor: string,
+    opts: FetchChildrenOpts,
+    onBatch: (assets: ClientAsset[], hasMore: boolean) => void,
+    cap: number = 5000,
+  ): Promise<void> {
+    let cursor: string | null = startCursor;
+    let total = 0;
+    while (cursor && total < cap) {
+      const result: { resources: any[]; next_cursor: string | null } = await this.sdk.search({
+        expression: `${query}*`,
+        sortBy: { field: 'created_at', direction: opts.sortDirection },
+        maxResults: 500,
+        nextCursor: cursor,
+        withField: ['tags', 'context', 'metadata'],
+      });
+      const assets = this.filterByResourceType(result.resources || [], opts.resourceTypeFilter)
+        .map((a: any) => this.toClientAsset(a));
+      cursor = result.next_cursor ?? null;
+      if (assets.length === 0) { continue; }
+      total += assets.length;
+      onBatch(assets, !!cursor && total < cap);
+    }
+  }
+
+  private filterByResourceType(resources: any[], filter: FetchChildrenOpts['resourceTypeFilter']): any[] {
+    return resources.filter((asset: any) => {
+      if (filter === 'all') {
+        return true;
+      }
+      return String(asset.resource_type).toLowerCase() === filter;
+    });
+  }
+
+  private toClientAsset(a: any): ClientAsset {
+    // Coerce unexpected resource_type values to 'image'; mirrors prior tree-provider fallback.
+    const resourceType = (a.resource_type === 'video' || a.resource_type === 'raw') ? a.resource_type : 'image';
+    const deliveryType = typeof a.type === 'string' ? a.type : undefined;
+    const isAuthenticated = deliveryType === 'authenticated';
+    const baseUrlOpts = {
+      resource_type: resourceType,
+      type: deliveryType,
+      secure: true,
+    };
+
+    const signedOriginal = isAuthenticated
+      ? this.sdk.urlFor(a.public_id, {
+          ...baseUrlOpts,
+          sign_url: true,
+          ...(resourceType !== 'raw' && a.format ? { format: String(a.format) } : {}),
+        })
+      : undefined;
+
+    const optimized = signedOriginal || this.sdk.urlFor(a.public_id, {
+      ...baseUrlOpts,
+      transformation: resourceType === 'raw'
+        ? undefined
+        : [{ fetch_format: resourceType === 'video' ? 'auto:video' : 'auto' }, { quality: 'auto' }],
+    });
+    const thumbnail = signedOriginal || (resourceType === 'raw'
+      ? optimized
+      : this.sdk.urlFor(a.public_id, {
+          ...baseUrlOpts,
+          transformation: [{ width: 160, height: 160, crop: 'fill', fetch_format: 'auto', quality: 'auto' }],
+        }));
+    return {
+      public_id: a.public_id,
+      display_name: a.display_name,
+      resource_type: resourceType,
+      type: deliveryType,
+      format: a.format,
+      bytes: a.bytes,
+      width: a.width,
+      height: a.height,
+      secure_url: signedOriginal || a.secure_url,
+      optimized_url: optimized,
+      thumbnail_url: thumbnail,
+      tags: a.tags,
+      context: a.context,
+      metadata: a.metadata,
+      created_at: a.created_at,
+    };
+  }
+
+  async fetchUploadPresets(): Promise<UploadPreset[]> {
+    if (!this.cloudName || !this.apiKey || !this.apiSecret) {
+      throw new Error('Cloudinary credentials not configured');
+    }
+    const result = await this.sdk.uploadPresets();
+    this.uploadPresets = result.presets.map((p) => ({
+      name: p.name,
+      signed: p.unsigned === false,
+      settings: p.settings,
+    }));
+    return this.uploadPresets;
+  }
+
+  async listAllFolders(maxDepth = 4): Promise<Array<{ path: string; name: string }>> {
+    const all: Array<{ path: string; name: string }> = [];
+
+    const visitLevel = async (paths: string[], depth: number): Promise<void> => {
+      if (paths.length === 0 || depth > maxDepth) {
+        return;
+      }
+
+      const results = await Promise.all(
+        paths.map((p) => this.sdk.subFolders(p))
+      );
+
+      const next: string[] = [];
+      for (const result of results) {
+        for (const folder of result.folders || []) {
+          all.push({ path: folder.path, name: folder.name });
+          next.push(folder.path);
+        }
+      }
+
+      await visitLevel(next, depth + 1);
+    };
+
+    await visitLevel([''], 0);
+    return all.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  getCurrentUploadPreset(): string | null {
+    if (this.uploadPreset && this.uploadPresets.some((p) => p.name === this.uploadPreset)) {
+      return this.uploadPreset;
+    }
+    return null;
+  }
+}
diff --git a/src/cloudinary/types.ts b/src/cloudinary/types.ts
new file mode 100644
index 0000000..319655f
--- /dev/null
+++ b/src/cloudinary/types.ts
@@ -0,0 +1,51 @@
+/**
+ * Plain-JSON asset record passed between service, host bridge, and webview.
+ * Intentionally flat and free of vscode.* types so it can be postMessage'd.
+ */
+export interface ClientAsset {
+  public_id: string;
+  display_name?: string;
+  resource_type: 'image' | 'video' | 'raw';
+  /** Cloudinary delivery type: 'upload' | 'authenticated' | 'private' | 'fetch'. */
+  type?: string;
+  format?: string;
+  bytes?: number;
+  width?: number;
+  height?: number;
+  secure_url: string;
+  /** Pre-computed delivery URL with f_auto,q_auto. Authenticated assets use the signed original URL. */
+  optimized_url: string;
+  /** Pre-computed thumbnail URL. Authenticated assets use the signed original URL instead of dynamic transforms. */
+  thumbnail_url: string;
+  tags?: string[];
+  context?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface ClientFolder {
+  name: string;
+  path: string;
+}
+
+export interface ChildrenPage {
+  folders: ClientFolder[];
+  assets: ClientAsset[];
+  nextCursor: string | null;
+}
+
+export type ResourceTypeFilter = 'all' | 'image' | 'video' | 'raw';
+export type SortDirection = 'asc' | 'desc';
+
+export interface FetchChildrenOpts {
+  resourceTypeFilter: ResourceTypeFilter;
+  sortDirection: SortDirection;
+  /** Pass a cursor from a previous ChildrenPage. Omit (or pass `undefined`) to start from the beginning. */
+  nextCursor?: string;
+}
+
+export interface UploadPreset {
+  name: string;
+  signed: boolean;
+  settings?: Record<string, unknown>;
+}
diff --git a/src/commands/clearSearch.ts b/src/commands/clearSearch.ts
index 4e67424..f5774c6 100644
--- a/src/commands/clearSearch.ts
+++ b/src/commands/clearSearch.ts
@@ -1,26 +1,24 @@
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { LibraryWebviewViewProvider } from "../webview/libraryView";
+
+type SearchAwareLibraryWebview = LibraryWebviewViewProvider & {
+    setSearch?: (query: string | null) => Thenable<void> | Promise<void>;
+};
 
 /**
  * Registers a command that clears the active search filter in the Cloudinary view.
  * @param context - The VS Code extension context.
- * @param provider - The Cloudinary tree data provider instance.
+ * @param libraryWebview - The Cloudinary library webview provider.
  */
 function registerClearSearch(
     context: vscode.ExtensionContext,
-    provider: CloudinaryTreeDataProvider
+    libraryWebview?: LibraryWebviewViewProvider
 ) {
     context.subscriptions.push(
-        vscode.commands.registerCommand("cloudinary.clearSearch", () => {
-            provider.refresh({
-                folderPath: '',
-                nextCursor: null,
-                searchQuery: null,
-                resourceTypeFilter: 'all'
-            });
-            vscode.window.showInformationMessage("🔍 Search filter cleared.");
+        vscode.commands.registerCommand("cloudinary.clearSearch", async () => {
+            await (libraryWebview as SearchAwareLibraryWebview | undefined)?.setSearch?.(null);
         })
     );
 }
 
-export default registerClearSearch;
\ No newline at end of file
+export default registerClearSearch;
diff --git a/src/commands/configureAiTools.ts b/src/commands/configureAiTools.ts
index d4af0c4..23554c6 100644
--- a/src/commands/configureAiTools.ts
+++ b/src/commands/configureAiTools.ts
@@ -6,6 +6,7 @@ import {
   MCP_SERVERS,
   detectEditor,
   getMcpFilePath,
+  getMcpRootKey,
   fetchSkillList,
   fetchSkillContent,
   installForClaudeCode,
@@ -25,8 +26,7 @@ async function createMcpConfig(
   mcpFilePath: string,
   createdFiles: string[]
 ): Promise<void> {
-  const rootKey = editor === "vscode" ? "servers" : "mcpServers";
-  const configuredKeys = await readConfiguredMcpServerKeys(rootUri, mcpFilePath, rootKey);
+  const configuredKeys = await readConfiguredMcpServerKeys(rootUri, mcpFilePath, getMcpRootKey(editor));
 
   const selected = await vscode.window.showQuickPick(
     MCP_SERVERS.map((s) => ({
@@ -85,13 +85,13 @@ function registerConfigureAiTools(context: vscode.ExtensionContext): void {
         const editor = detectEditor();
         const ideOptions: vscode.QuickPickItem[] = [
           { label: "Claude Code", description: "Install to .claude/skills/" },
-          { label: "Cursor",      description: "Install to .cursor/rules/" },
+          { label: "Cursor", description: "Install to .cursor/rules/" },
           { label: "VS Code (Copilot)", description: "Append to .github/copilot-instructions.md" },
         ];
         const defaultLabel =
           editor === "cursor" ? "Cursor" :
-          editor === "vscode" ? "VS Code (Copilot)" :
-          "Claude Code";
+            editor === "vscode" ? "VS Code (Copilot)" :
+              "Claude Code";
 
         const qp = vscode.window.createQuickPick();
         qp.items = ideOptions;
@@ -171,7 +171,7 @@ function registerConfigureAiTools(context: vscode.ExtensionContext): void {
 
       if (createdFiles.length > 0) {
         const action = await vscode.window.showInformationMessage(
-          `✅ Configured AI tools: ${createdFiles.join(", ")}`,
+          `$(check) Configured AI tools: ${createdFiles.join(", ")}`,
           "Open File"
         );
         if (action === "Open File") {
diff --git a/src/commands/copyCommands.ts b/src/commands/copyCommands.ts
index edafe8d..ef7b862 100644
--- a/src/commands/copyCommands.ts
+++ b/src/commands/copyCommands.ts
@@ -1,10 +1,11 @@
 import * as vscode from "vscode";
+import { AnalyticsService } from "../analytics/analyticsService";
 
 /**
  * Registers clipboard-related commands for copying asset details from Cloudinary.
  * @param context - The VS Code extension context.
  */
-function registerClipboard(context: vscode.ExtensionContext) {
+function registerClipboard(context: vscode.ExtensionContext, analytics?: AnalyticsService) {
   context.subscriptions.push(
     vscode.commands.registerCommand(
       "cloudinary.copyUrl",
@@ -15,6 +16,7 @@ function registerClipboard(context: vscode.ExtensionContext) {
           return;
         }
         vscode.env.clipboard.writeText(secureUrl).then(() => {
+          analytics?.track("copy_asset_url", { copy_type: "secure_url" });
           vscode.window.showInformationMessage(`Copied URL: ${secureUrl}`);
         });
       }
@@ -31,6 +33,7 @@ function registerClipboard(context: vscode.ExtensionContext) {
           return;
         }
         vscode.env.clipboard.writeText(publicId).then(() => {
+          analytics?.track("copy_asset_public_id", { copy_type: "public_id" });
           vscode.window.showInformationMessage(`Copied Public ID: ${publicId}`);
         });
       }
@@ -47,6 +50,7 @@ function registerClipboard(context: vscode.ExtensionContext) {
           return;
         }
         vscode.env.clipboard.writeText(optimizedUrl).then(() => {
+          analytics?.track("copy_asset_url", { copy_type: "optimized_url" });
           vscode.window.showInformationMessage(`Copied Optimized URL: ${optimizedUrl}`);
         });
       }
diff --git a/src/commands/previewAsset.ts b/src/commands/previewAsset.ts
index 29d208d..2462898 100644
--- a/src/commands/previewAsset.ts
+++ b/src/commands/previewAsset.ts
@@ -1,4 +1,5 @@
 import * as vscode from "vscode";
+import { AnalyticsService } from "../analytics/analyticsService";
 import { createWebviewDocument, getScriptUri } from "../webview/webviewUtils";
 import { escapeHtml, formatFileSize } from "../webview/utils/helpers";
 import { assetIcons, actionIcons } from "../webview/icons";
@@ -14,6 +15,7 @@ type AssetData = {
   filename: string;
   format?: string;
   resource_type?: string;
+  type?: string;
   tags?: string[];
   context?: Record<string, any>;
   metadata?: Record<string, any>;
@@ -38,12 +40,17 @@ function getAssetIcon(type: string): string {
   }
 }
 
-function registerPreview(context: vscode.ExtensionContext) {
+function registerPreview(context: vscode.ExtensionContext, analytics?: AnalyticsService) {
   context.subscriptions.push(
     vscode.commands.registerCommand(
       "cloudinary.openAsset",
       (asset: AssetData) => {
         const publicId = asset.public_id;
+        analytics?.track("asset_opened", {
+          resource_type: asset.resource_type || asset.displayType,
+          asset_type: asset.type,
+          entry_point: "preview_command",
+        });
 
         // Check if panel for this asset already exists
         const existingPanel = openPanels.get(publicId);
@@ -112,6 +119,7 @@ function registerPreview(context: vscode.ExtensionContext) {
         panel.webview.onDidReceiveMessage(async (message) => {
           if (message.command === "copyToClipboard" && message.text) {
             await vscode.env.clipboard.writeText(message.text);
+            analytics?.track("copy_asset_url", { copy_type: "preview" });
           }
         });
       }
@@ -135,6 +143,17 @@ function getAssetTypeIcon(type: string): string {
   return getAssetIcon(type);
 }
 
+function isAuthenticatedAsset(asset: AssetData): boolean {
+  return asset.type === "authenticated";
+}
+
+function buildAuthenticatedBadgeHtml(asset: AssetData): string {
+  if (!isAuthenticatedAsset(asset)) {
+    return "";
+  }
+  return `<span class="badge badge--auth">${actionIcons.lock("sm")} Authenticated</span>`;
+}
+
 /**
  * Build the preview section HTML based on asset type.
  */
@@ -219,6 +238,30 @@ function buildMetadataHtml(data: Record<string, any> | undefined, emptyText: str
     .join("");
 }
 
+function buildUrlItem(label: string, url: string): string {
+  return `
+    <div class="url-item">
+      <div class="url-item__label">${escapeHtml(label)}</div>
+      <div class="url-item__value">
+        <a href="${escapeHtml(url)}" target="_blank" class="url-item__link">${escapeHtml(url)}</a>
+        <button class="btn btn--secondary btn--sm btn--copy" data-copy="${escapeHtml(url)}">Copy</button>
+      </div>
+    </div>
+  `;
+}
+
+function buildUrlsHtml(asset: AssetData): string {
+  if (isAuthenticatedAsset(asset)) {
+    const signedUrl = asset.secure_url || asset.optimized_url;
+    const extraOptimized = asset.optimized_url && asset.optimized_url !== signedUrl
+      ? buildUrlItem("Optimized URL", asset.optimized_url)
+      : "";
+    return `${buildUrlItem("Signed authenticated URL", signedUrl)}${extraOptimized}`;
+  }
+
+  return `${buildUrlItem("Original URL", asset.secure_url)}${buildUrlItem("Optimized URL", asset.optimized_url)}`;
+}
+
 /**
  * Build the lightbox HTML.
  */
@@ -250,6 +293,8 @@ function getPreviewContent(asset: AssetData): string {
   const contextHtml = buildMetadataHtml(asset.context, "No context metadata");
   const metadataHtml = buildMetadataHtml(asset.metadata, "No structured metadata");
   const lightboxHtml = hasEnlarge ? buildLightboxHtml(asset) : "";
+  const authenticatedBadgeHtml = buildAuthenticatedBadgeHtml(asset);
+  const urlsHtml = buildUrlsHtml(asset);
 
   return `
     <div class="card card--elevated" style="max-width: 600px; width: 100%;">
@@ -261,6 +306,7 @@ function getPreviewContent(asset: AssetData): string {
             <h2 class="asset-header__title" title="${escapeHtml(asset.public_id)}">${escapeHtml(displayName || "")}</h2>
             <div class="asset-header__subtitle">
               <span class="badge">${escapeHtml((asset.format || asset.displayType || "unknown").toUpperCase())}</span>
+              ${authenticatedBadgeHtml}
               ${asset.width && asset.height ? `${asset.width} × ${asset.height}` : ""}
               ${asset.bytes ? ` • ${formatFileSize(asset.bytes)}` : ""}
             </div>
@@ -301,6 +347,10 @@ function getPreviewContent(asset: AssetData): string {
               <span class="info-row__label">Type</span>
               <span class="info-row__value">${escapeHtml(asset.displayType || "unknown")}</span>
             </div>
+            <div class="info-row">
+              <span class="info-row__label">Delivery</span>
+              <span class="info-row__value">${escapeHtml(asset.type || "upload")}${authenticatedBadgeHtml}</span>
+            </div>
           </div>
 
           <div class="tabs__content" id="tab-meta" role="tabpanel">
@@ -319,20 +369,7 @@ function getPreviewContent(asset: AssetData): string {
           </div>
 
           <div class="tabs__content" id="tab-urls" role="tabpanel">
-            <div class="url-item">
-              <div class="url-item__label">Original URL</div>
-              <div class="url-item__value">
-                <a href="${escapeHtml(asset.secure_url)}" target="_blank" class="url-item__link">${escapeHtml(asset.secure_url)}</a>
-                <button class="btn btn--secondary btn--sm btn--copy" data-copy="${escapeHtml(asset.secure_url)}">Copy</button>
-              </div>
-            </div>
-            <div class="url-item">
-              <div class="url-item__label">Optimized URL</div>
-              <div class="url-item__value">
-                <a href="${escapeHtml(asset.optimized_url)}" target="_blank" class="url-item__link">${escapeHtml(asset.optimized_url)}</a>
-                <button class="btn btn--secondary btn--sm btn--copy" data-copy="${escapeHtml(asset.optimized_url)}">Copy</button>
-              </div>
-            </div>
+            ${urlsHtml}
           </div>
         </div>
       </div>
diff --git a/src/commands/registerCommands.ts b/src/commands/registerCommands.ts
index 46929f4..009da2e 100644
--- a/src/commands/registerCommands.ts
+++ b/src/commands/registerCommands.ts
@@ -8,54 +8,102 @@ import registerSwitchEnv from "./switchEnvironment";
 import registerClearSearch from "./clearSearch";
 import registerWelcomeScreen from "./welcomeScreen";
 import registerConfigureAiTools from "./configureAiTools";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { CloudinaryService } from "../cloudinary/cloudinaryService";
 import { HomescreenViewProvider } from "../webview/homescreenView";
+import { LibraryWebviewViewProvider } from "../webview/libraryView";
+import { DocsAiViewProvider } from "../webview/docsAiView";
+import { AnalyticsService } from "../analytics/analyticsService";
 
 /**
  * Registers all Cloudinary-related commands with the VS Code command registry.
  * @param context - The extension context.
- * @param provider - The Cloudinary tree data provider.
+ * @param cloudinaryService - The shared Cloudinary service.
  * @param statusBar - Status bar item to show current environment.
  * @param homescreenProvider - The homescreen webview view provider.
  */
 function registerAllCommands(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider,
+  cloudinaryService: CloudinaryService,
+  environmentTarget: Parameters<typeof registerSwitchEnv>[1],
   statusBar: vscode.StatusBarItem,
-  homescreenProvider: HomescreenViewProvider
+  homescreenProvider: HomescreenViewProvider,
+  libraryWebview: LibraryWebviewViewProvider,
+  docsAiProvider: DocsAiViewProvider,
+  analytics?: AnalyticsService
 ) {
   context.subscriptions.push(
     vscode.commands.registerCommand("cloudinary.showHomescreen", () => {
+      analytics?.track("home_opened", { entry_point: "command" });
+      docsAiProvider.requestRecentConversations();
       vscode.commands.executeCommand("setContext", "cloudinary.activeView", "homescreen");
+      vscode.commands.executeCommand("workbench.view.extension.cloudinary");
+      setTimeout(() => {
+        void homescreenProvider.refresh();
+      }, 150);
     })
   );
 
   context.subscriptions.push(
-    vscode.commands.registerCommand("cloudinary.showLibrary", () => {
+    vscode.commands.registerCommand("cloudinary.showLibrary", (initialSearchQuery?: string) => {
+      const query = typeof initialSearchQuery === "string" && initialSearchQuery.trim()
+        ? initialSearchQuery.trim()
+        : null;
+      analytics?.track("library_opened", { entry_point: query ? "search" : "command" });
+      if (query) {
+        void libraryWebview.setSearch(query);
+      }
       vscode.commands.executeCommand("setContext", "cloudinary.activeView", "library");
       vscode.commands.executeCommand("workbench.view.extension.cloudinary");
     })
   );
 
   context.subscriptions.push(
-    vscode.commands.registerCommand("cloudinary.refresh", () =>
-      provider.refresh({
-        folderPath: '',
-        nextCursor: null,
-        searchQuery: null,
-        resourceTypeFilter: 'all'
-      })
-    )
+    vscode.commands.registerCommand("cloudinary.showDocsAI", (initialPrompt?: string) => {
+      analytics?.track("docs_ai_opened", {
+        entry_point: "command",
+        has_initial_prompt: !!initialPrompt,
+      });
+      docsAiProvider.queuePrompt(initialPrompt);
+      vscode.commands.executeCommand("setContext", "cloudinary.activeView", "docsAi");
+      vscode.commands.executeCommand("workbench.view.extension.cloudinary");
+      setTimeout(() => {
+        vscode.commands.executeCommand("cloudinaryDocsAI.focus");
+        docsAiProvider.flushPendingPrompt(250);
+      }, 150);
+    })
+  );
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand("cloudinary.showDocsAIConversation", (conversationId?: string) => {
+      analytics?.track("docs_ai_opened", {
+        entry_point: "command",
+        has_initial_conversation: !!conversationId,
+      });
+      docsAiProvider.queueConversation(conversationId);
+      vscode.commands.executeCommand("setContext", "cloudinary.activeView", "docsAi");
+      vscode.commands.executeCommand("workbench.view.extension.cloudinary");
+      setTimeout(() => {
+        vscode.commands.executeCommand("cloudinaryDocsAI.focus");
+        docsAiProvider.flushPendingConversation(250);
+      }, 150);
+    })
+  );
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand("cloudinary.refresh", async () => {
+      analytics?.track("library_refreshed", { entry_point: "command" });
+      await libraryWebview.refresh();
+    })
   );
 
-  registerSearch(context, provider, homescreenProvider);
-  registerClearSearch(context, provider);
-  registerViewOptions(context, provider);
-  registerPreview(context);
-  registerUpload(context, provider);
-  registerClipboard(context);
-  registerSwitchEnv(context, provider, statusBar);
-  registerWelcomeScreen(context, provider);
+  registerSearch(context, homescreenProvider);
+  registerClearSearch(context, libraryWebview);
+  registerViewOptions(context, libraryWebview);
+  registerPreview(context, analytics);
+  registerUpload(context, cloudinaryService, analytics);
+  registerClipboard(context, analytics);
+  registerSwitchEnv(context, environmentTarget, statusBar, analytics);
+  registerWelcomeScreen(context, cloudinaryService);
   registerConfigureAiTools(context);
 }
 
diff --git a/src/commands/searchAssets.ts b/src/commands/searchAssets.ts
index f432f34..bf88462 100644
--- a/src/commands/searchAssets.ts
+++ b/src/commands/searchAssets.ts
@@ -1,13 +1,8 @@
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
 import { HomescreenViewProvider } from "../webview/homescreenView";
 
-/**
- * Registers the search command. Opens the dashboard and focuses its search input.
- */
 function registerSearch(
   context: vscode.ExtensionContext,
-  _provider: CloudinaryTreeDataProvider,
   homescreenProvider: HomescreenViewProvider
 ) {
   context.subscriptions.push(
diff --git a/src/commands/switchEnvironment.ts b/src/commands/switchEnvironment.ts
index 8600975..1f1d1b3 100644
--- a/src/commands/switchEnvironment.ts
+++ b/src/commands/switchEnvironment.ts
@@ -1,9 +1,12 @@
 import * as vscode from "vscode";
 import { v2 as cloudinary } from "cloudinary";
+import { CloudinaryService, Credentials } from "../cloudinary/cloudinaryService";
 import { loadEnvironments, getGlobalConfigPath } from "../config/configUtils";
-import detectFolderMode from "../config/detectFolderMode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { detectFolderModeResult, resolveFolderModeState } from "../config/detectFolderMode";
+import { readFolderModeCache, writeFolderModeCache } from "../config/folderModeCache";
 import { generateUserAgent } from "../utils/userAgent";
+import { AnalyticsService } from "../analytics/analyticsService";
+import { trackConfigValidation } from "../analytics/trackConfigValidation";
 
 interface CloudinaryEnvironment {
   apiKey: string;
@@ -11,16 +14,70 @@ interface CloudinaryEnvironment {
   uploadPreset?: string;  // Optional: Default upload preset
 }
 
+type EnvironmentTarget = Pick<
+  CloudinaryService,
+  "cloudName" | "apiKey" | "apiSecret" | "uploadPreset" | "dynamicFolders" | "credentialsValid"
+> & {
+  setCredentials?: (creds: Credentials) => void;
+};
+
+function updateEnvironmentTarget(
+  target: EnvironmentTarget,
+  credentials: Credentials,
+  credentialsValid: boolean | undefined
+) {
+  target.credentialsValid = credentialsValid;
+
+  if (typeof target.setCredentials === "function") {
+    target.setCredentials(credentials);
+    return;
+  }
+
+  target.cloudName = credentials.cloudName;
+  target.apiKey = credentials.apiKey;
+  target.apiSecret = credentials.apiSecret;
+  target.uploadPreset = credentials.uploadPreset ?? null;
+  target.dynamicFolders = credentials.dynamicFolders ?? false;
+}
+
+function getStatusBarText(
+  cloudName: string,
+  dynamicFolders: boolean,
+  credentialsValid?: boolean
+): string {
+  if (credentialsValid === false) {
+    return `$(warning) ${cloudName}: credentials invalid`;
+  }
+  if (credentialsValid === undefined) {
+    return `$(cloud) ${cloudName}`;
+  }
+  const folderMode = dynamicFolders ? "Dynamic" : "Fixed";
+  return `$(cloud) ${cloudName} $(folder) ${folderMode}`;
+}
+
+function getStatusBarTooltip(dynamicFolders: boolean, credentialsValid?: boolean): string {
+  if (credentialsValid === false) {
+    return "Cloudinary credentials are invalid or unauthorized.\n\nClick to switch environment, or update your config.";
+  }
+  if (credentialsValid === undefined) {
+    return "Click to switch Cloudinary environment";
+  }
+  return dynamicFolders
+    ? "Click to switch Cloudinary environment\n\nDynamic Folders: Assets can be organized independently of their public ID"
+    : "Click to switch Cloudinary environment\n\nFixed Folders: Asset folder is determined by public ID path";
+}
+
 /**
  * Registers commands for switching Cloudinary environments and editing global config.
  * @param context - Extension context (includes global state).
- * @param provider - Cloudinary data provider to update credentials.
+ * @param target - Cloudinary environment target to update credentials on.
  * @param statusBar - VS Code status bar item to reflect environment change.
  */
 function registerSwitchEnv(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider,
-  statusBar: vscode.StatusBarItem
+  target: EnvironmentTarget,
+  statusBar: vscode.StatusBarItem,
+  analytics?: AnalyticsService
 ) {
   context.subscriptions.push(
     vscode.commands.registerCommand(
@@ -30,7 +87,7 @@ function registerSwitchEnv(
         const cloudNames = Object.keys(environments);
 
         if (cloudNames.length === 0) {
-          vscode.window.showErrorMessage("❌ No Cloudinary environments found in config.");
+          vscode.window.showErrorMessage("No Cloudinary environments found in config.");
           return;
         }
 
@@ -40,25 +97,30 @@ function registerSwitchEnv(
 
         if (selected) {
           const env = environments[selected];
+          const cached = readFolderModeCache(context.globalState, selected);
+
+          // Always validate the current credentials. The folder-mode cache is
+          // keyed only by cloud name, so it can provide a fallback mode but
+          // cannot prove that the current API key/secret are valid.
+          const result = await detectFolderModeResult(
+            selected,
+            env.apiKey,
+            env.apiSecret
+          );
+          trackConfigValidation(analytics, result, "switch");
 
-          provider.cloudName = selected;
-          provider.apiKey = env.apiKey;
-          provider.apiSecret = env.apiSecret;
-          provider.uploadPreset = env.uploadPreset || null;
-
-          const cacheKey = `cloudinary.dynamicFolders.${selected}`;
-          const cachedFolderMode = context.globalState.get(cacheKey) as boolean | undefined;
-
-          if (typeof cachedFolderMode === "boolean") {
-            provider.dynamicFolders = cachedFolderMode;
-          } else {
-            provider.dynamicFolders = await detectFolderMode(
-              selected,
-              env.apiKey,
-              env.apiSecret
-            );
-            context.globalState.update(cacheKey, provider.dynamicFolders);
+          if (result.outcome === "success") {
+            await writeFolderModeCache(context.globalState, selected, result.dynamicFolders);
           }
+          const { dynamicFolders, credentialsValid } = resolveFolderModeState(result, cached);
+
+          updateEnvironmentTarget(target, {
+            cloudName: selected,
+            apiKey: env.apiKey,
+            apiSecret: env.apiSecret,
+            uploadPreset: env.uploadPreset || null,
+            dynamicFolders,
+          }, credentialsValid);
 
           (cloudinary.utils as any).userPlatform = generateUserAgent();
 
@@ -68,25 +130,18 @@ function registerSwitchEnv(
             api_secret: env.apiSecret,
           });
 
-          // Update status bar with folder mode indicator
-          const folderMode = provider.dynamicFolders ? "Dynamic" : "Fixed";
-          statusBar.text = `$(cloud) ${selected} $(folder) ${folderMode}`;
-          statusBar.tooltip = provider.dynamicFolders
-            ? "Click to switch Cloudinary environment\n\nDynamic Folders: Assets can be organized independently of their public ID"
-            : "Click to switch Cloudinary environment\n\nFixed Folders: Asset folder is determined by public ID path";
-
-          provider.refresh({
-            folderPath: '',
-            nextCursor: null,
-            searchQuery: null,
-            resourceTypeFilter: 'all'
-          });
-
-          provider.notifyEnvironmentChange();
+          statusBar.text = getStatusBarText(selected, dynamicFolders, credentialsValid);
+          statusBar.tooltip = getStatusBarTooltip(dynamicFolders, credentialsValid);
 
-          vscode.window.showInformationMessage(
-            `🔄 Switched to ${selected} environment.`
-          );
+          if (credentialsValid === false) {
+            vscode.window.showWarningMessage(
+              `Switched to ${selected}, but its Cloudinary credentials are invalid or unauthorized.`
+            );
+          } else {
+            vscode.window.showInformationMessage(
+              `Switched to ${selected} environment.`
+            );
+          }
         }
       }
     )
diff --git a/src/commands/uploadWidget.ts b/src/commands/uploadWidget.ts
index f510c9e..4c3828a 100644
--- a/src/commands/uploadWidget.ts
+++ b/src/commands/uploadWidget.ts
@@ -1,5 +1,7 @@
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { AnalyticsService } from "../analytics/analyticsService";
+import { CloudinaryService } from "../cloudinary/cloudinaryService";
+import { UploadPreset } from "../cloudinary/types";
 import { v2 as cloudinary } from "cloudinary";
 import { Readable } from "stream";
 import {
@@ -16,6 +18,30 @@ interface FolderOption {
   label: string;
 }
 
+type UploadWidgetCloudinaryState = Pick<
+  CloudinaryService,
+  "cloudName" | "apiKey" | "apiSecret" | "uploadPresets" | "dynamicFolders"
+> & {
+  fetchUploadPresets(): Promise<UploadPreset[]>;
+  getCurrentUploadPreset(): string | null;
+  listAllFolders(maxDepth?: number): Promise<Array<{ path: string; name: string }>>;
+};
+
+type UploadWidgetCloudinaryStateTarget =
+  | UploadWidgetCloudinaryState
+  | {
+    service?: UploadWidgetCloudinaryState;
+  };
+
+function hasUploadWidgetCloudinaryState(
+  value: UploadWidgetCloudinaryStateTarget
+): value is UploadWidgetCloudinaryState {
+  return (
+    "fetchUploadPresets" in value &&
+    typeof value.fetchUploadPresets === "function"
+  );
+}
+
 /**
  * Singleton panel instance for the upload widget.
  */
@@ -35,19 +61,103 @@ const CHUNKED_UPLOAD_THRESHOLD = 20 * 1024 * 1024;
  * Chunk size for chunked uploads (6 MB).
  */
 const UPLOAD_CHUNK_SIZE = 6 * 1024 * 1024;
+const FOLDER_LOAD_FALLBACK_MS = 4000;
+// Safety cap on waiting for the client's "ready" handshake. The handshake
+// normally resolves in tens of ms (as soon as the webview script loads); this
+// only prevents an indefinite hang if the message is somehow never received.
+const READY_HANDSHAKE_TIMEOUT_MS = 5000;
+const ROOT_FOLDER_OPTIONS: FolderOption[] = [{ path: "", label: "/ (root)" }];
+const folderOptionsCache = new Map<string, FolderOption[]>();
+
+function cloneFolderOptions(folders: FolderOption[]): FolderOption[] {
+  return folders.map((folder) => ({ ...folder }));
+}
+
+function getCachedFolderOptions(cloudName: string | null | undefined): FolderOption[] | undefined {
+  if (!cloudName) {
+    return undefined;
+  }
+
+  const cached = folderOptionsCache.get(cloudName);
+  return cached ? cloneFolderOptions(cached) : undefined;
+}
+
+function setCachedFolderOptions(cloudName: string | null | undefined, folders: FolderOption[]): void {
+  if (!cloudName) {
+    return;
+  }
+
+  folderOptionsCache.set(cloudName, cloneFolderOptions(folders));
+}
+
+function getInitialFolderOptions(cloudName: string | null | undefined): FolderOption[] {
+  return getCachedFolderOptions(cloudName) ?? cloneFolderOptions(ROOT_FOLDER_OPTIONS);
+}
+
+function clearFolderOptionsCache(): void {
+  folderOptionsCache.clear();
+}
+
+function getUploadAssetResourceType(asset: any): string {
+  return asset.resource_type || "raw";
+}
+
+function getSignedOriginalUrl(asset: any, resourceType: string): string | undefined {
+  if (asset.type !== "authenticated") {
+    return undefined;
+  }
+
+  return cloudinary.url(asset.public_id, {
+    resource_type: resourceType,
+    type: asset.type,
+    secure: true,
+    sign_url: true,
+    ...(resourceType !== "raw" && asset.format ? { format: asset.format } : {}),
+  });
+}
+
+function getOptimizedUrl(asset: any, resourceType: string): string {
+  const signedOriginalUrl = getSignedOriginalUrl(asset, resourceType);
+  if (signedOriginalUrl) {
+    return signedOriginalUrl;
+  }
+
+  return resourceType === "raw"
+    ? cloudinary.url(asset.public_id, { resource_type: "raw", type: asset.type, secure: true })
+    : cloudinary.url(asset.public_id, {
+      resource_type: resourceType,
+      type: asset.type,
+      secure: true,
+      transformation: [
+        { fetch_format: resourceType === "video" ? "auto:video" : "auto" },
+        { quality: "auto" },
+      ],
+    });
+}
+
+function withSignedAuthenticatedUrl(asset: any): any {
+  const resourceType = getUploadAssetResourceType(asset);
+  const signedOriginalUrl = getSignedOriginalUrl(asset, resourceType);
+  return signedOriginalUrl
+    ? { ...asset, secure_url: signedOriginalUrl }
+    : asset;
+}
 
 /**
  * Registers commands for the Cloudinary upload widget.
  */
 function registerUpload(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryStateTarget: UploadWidgetCloudinaryStateTarget,
+  analytics?: AnalyticsService
 ) {
+  const cloudinaryState = getUploadCloudinaryState(cloudinaryStateTarget);
+
   context.subscriptions.push(
     vscode.commands.registerCommand("cloudinary.openUploadWidget", async () => {
       try {
-        await provider.fetchUploadPresets();
-        openOrRevealUploadPanel("", provider, context);
+        analytics?.track("upload_widget_opened", { entry_point: "command" });
+        await openOrRevealUploadPanel("", cloudinaryState, context, analytics);
       } catch (err: any) {
         vscode.window.showErrorMessage(
           `Failed to open upload widget: ${err.message}`
@@ -61,9 +171,12 @@ function registerUpload(
       "cloudinary.uploadToFolder",
       async (folderItem: { label: string; data: { path?: string } }) => {
         try {
-          await provider.fetchUploadPresets();
           const folderPath = folderItem.data.path || "";
-          openOrRevealUploadPanel(folderPath, provider, context);
+          analytics?.track("upload_widget_opened", {
+            entry_point: "folder_context",
+            folder_selected: !!folderPath,
+          });
+          await openOrRevealUploadPanel(folderPath, cloudinaryState, context, analytics);
         } catch (err: any) {
           vscode.window.showErrorMessage(
             `Failed to open upload widget: ${err.message}`
@@ -87,32 +200,63 @@ export function resetUploadPanel(): void {
   uploadPanel = undefined;
 }
 
+function getUploadCloudinaryState(
+  cloudinaryStateTarget: UploadWidgetCloudinaryStateTarget
+): UploadWidgetCloudinaryState {
+  if (hasUploadWidgetCloudinaryState(cloudinaryStateTarget)) {
+    return cloudinaryStateTarget;
+  }
+
+  const service = cloudinaryStateTarget.service;
+  if (!service) {
+    throw new Error("Cloudinary service is unavailable");
+  }
+
+  return service;
+}
+
 /**
  * Opens the upload panel or reveals it if already open.
  */
-function openOrRevealUploadPanel(
+async function openOrRevealUploadPanel(
   folderPath: string,
-  provider: CloudinaryTreeDataProvider,
-  context: vscode.ExtensionContext
-) {
+  cloudinaryState: UploadWidgetCloudinaryState,
+  context: vscode.ExtensionContext,
+  analytics?: AnalyticsService
+): Promise<void> {
   currentFolderPath = folderPath;
 
   if (uploadPanel) {
-    uploadPanel.reveal(vscode.ViewColumn.One);
-    uploadPanel.webview.postMessage({
-      command: "setFolder",
-      folderPath: folderPath,
-    });
-    return;
+    try {
+      uploadPanel.reveal(vscode.ViewColumn.One);
+      uploadPanel.webview.postMessage({
+        command: "setFolder",
+        folderPath: folderPath,
+      });
+      return;
+    } catch {
+      uploadPanel = undefined;
+    }
   }
 
-  uploadPanel = createUploadPanel(provider, context);
+  uploadPanel = await createUploadPanel(cloudinaryState, context, analytics);
 
   uploadPanel.onDidDispose(() => {
     uploadPanel = undefined;
   });
 }
 
+/**
+ * Posts a message to a webview panel, swallowing errors if the panel was disposed.
+ */
+function safePostToPanel(panel: vscode.WebviewPanel, message: unknown): void {
+  try {
+    panel.webview.postMessage(message);
+  } catch {
+    // Panel disposed between post calls; safe to ignore.
+  }
+}
+
 /**
  * Uploads a file with progress tracking.
  */
@@ -129,12 +273,12 @@ async function uploadWithProgress(
   return new Promise((resolve, reject) => {
     const uploadStream = useChunkedUpload
       ? cloudinary.uploader.upload_chunked_stream(
-          { ...options, chunk_size: UPLOAD_CHUNK_SIZE },
-          (error, result) => (error ? reject(error) : resolve(result))
-        )
+        { ...options, chunk_size: UPLOAD_CHUNK_SIZE },
+        (error, result) => (error ? reject(error) : resolve(result))
+      )
       : cloudinary.uploader.upload_stream(options, (error, result) =>
-          error ? reject(error) : resolve(result)
-        );
+        error ? reject(error) : resolve(result)
+      );
 
     let uploaded = 0;
     const total = buffer.length;
@@ -146,7 +290,7 @@ async function uploadWithProgress(
         if (chunk.length > 0) {
           uploaded += chunk.length;
           const percent = Math.round((uploaded / total) * 100);
-          panel.webview.postMessage({
+          safePostToPanel(panel, {
             command: "uploadProgress",
             fileId,
             percent,
@@ -163,21 +307,46 @@ async function uploadWithProgress(
 }
 
 /**
- * Collects folder options from the provider's cache.
+ * Collects folder options from the Cloudinary service.
  */
-function collectFolderOptions(provider: CloudinaryTreeDataProvider): FolderOption[] {
-  const folders: FolderOption[] = [{ path: "", label: "/ (root)" }];
-  for (const folder of provider.getAvailableFolders()) {
-    folders.push({ path: folder.path, label: folder.path });
+async function collectFolderOptions(
+  cloudinaryState: UploadWidgetCloudinaryState
+): Promise<FolderOption[]> {
+  const folders: FolderOption[] = [...ROOT_FOLDER_OPTIONS];
+  const seenPaths = new Set<string>();
+  const cachedFolders = getCachedFolderOptions(cloudinaryState.cloudName);
+
+  try {
+    for (const folder of await cloudinaryState.listAllFolders()) {
+      if (!folder.path || seenPaths.has(folder.path)) {
+        continue;
+      }
+
+      seenPaths.add(folder.path);
+      folders.push({ path: folder.path, label: folder.path });
+    }
+  } catch {
+    return cachedFolders ?? folders;
   }
+
+  setCachedFolderOptions(cloudinaryState.cloudName, folders);
   return folders;
 }
 
+// Exported for the extension test harness; not part of the command surface.
+export const uploadWidgetTestApi = {
+  clearFolderOptionsCache,
+  collectFolderOptions,
+  getUploadOptions,
+  getInitialFolderOptions,
+  getUploadContent,
+};
+
 /**
  * Creates upload options for the Cloudinary API.
  */
 function getUploadOptions(
-  provider: CloudinaryTreeDataProvider,
+  cloudinaryState: UploadWidgetCloudinaryState,
   presetName: string | null | undefined,
   folder: string,
   publicId?: string,
@@ -191,7 +360,7 @@ function getUploadOptions(
   }
 
   if (folder) {
-    if (provider.dynamicFolders) {
+    if (cloudinaryState.dynamicFolders) {
       options.asset_folder = folder;
     } else {
       options.folder = folder;
@@ -200,7 +369,7 @@ function getUploadOptions(
 
   if (fileName) {
     options.filename_override = fileName;
-    if (provider.dynamicFolders) {
+    if (cloudinaryState.dynamicFolders) {
       options.display_name = fileName.replace(/\.[^/.]+$/, "");
     }
   }
@@ -222,11 +391,12 @@ function getUploadOptions(
 /**
  * Creates the webview panel with custom upload UI.
  */
-function createUploadPanel(
-  provider: CloudinaryTreeDataProvider,
-  context: vscode.ExtensionContext
-): vscode.WebviewPanel {
-  const cloudName = provider.cloudName!;
+async function createUploadPanel(
+  cloudinaryState: UploadWidgetCloudinaryState,
+  context: vscode.ExtensionContext,
+  analytics?: AnalyticsService
+): Promise<vscode.WebviewPanel> {
+  const cloudName = cloudinaryState.cloudName!;
   const panel = vscode.window.createWebviewPanel(
     "cloudinaryUploadWidget",
     `Upload — ${cloudName}`,
@@ -246,8 +416,17 @@ function createUploadPanel(
     "cloudinary_icon_blue.png"
   );
 
-  const currentPreset = provider.getCurrentUploadPreset() || "";
-  const folders = collectFolderOptions(provider);
+  const currentPreset = cloudinaryState.getCurrentUploadPreset() || "";
+  const initialFolders = getInitialFolderOptions(cloudName);
+
+  // The client posts "ready" once its message listener is attached. The deferred
+  // load below waits on this before posting folders/presets, so updates can't be
+  // dropped by landing before the listener exists (a fixed delay races the
+  // webview's load time and was the cause of the empty-dropdown bug).
+  let resolveClientReady: (() => void) | undefined;
+  const clientReady = new Promise<void>((resolve) => {
+    resolveClientReady = resolve;
+  });
 
   const uploadScriptUri = getScriptUri(
     panel.webview,
@@ -255,8 +434,9 @@ function createUploadPanel(
     "upload-widget.js"
   );
 
-  // Configuration to pass to the webview
-  const presetsJson = JSON.stringify(provider.uploadPresets);
+  // Configuration to pass to the webview. Render with cached presets/folders
+  // immediately; refresh asynchronously below to avoid blocking the panel open.
+  const presetsJson = JSON.stringify(cloudinaryState.uploadPresets);
   const initScript = `
     initUploadWidget({
       cloudName: ${JSON.stringify(cloudName)},
@@ -264,18 +444,14 @@ function createUploadPanel(
     });
   `;
 
-  panel.webview.html = createWebviewDocument({
-    title: "Upload to Cloudinary",
-    webview: panel.webview,
-    extensionUri: context.extensionUri,
-    bodyContent: getUploadContent(currentPreset, provider, currentFolderPath, folders),
-    bodyClass: "layout-centered",
-    additionalScripts: [uploadScriptUri],
-    inlineScript: initScript,
-  });
-
   // Handle messages from the webview
   panel.webview.onDidReceiveMessage(async (message: any) => {
+    if (message.command === "ready") {
+      resolveClientReady?.();
+      resolveClientReady = undefined;
+      return;
+    }
+
     if (message.command === "folderChanged" && message.folderPath !== undefined) {
       currentFolderPath = message.folderPath;
       return;
@@ -285,7 +461,7 @@ function createUploadPanel(
       const presetName = message.preset !== undefined ? message.preset : currentPreset;
       const folder = message.folderPath !== undefined ? message.folderPath : currentFolderPath;
       const options = getUploadOptions(
-        provider,
+        cloudinaryState,
         presetName,
         folder,
         message.publicId,
@@ -294,21 +470,40 @@ function createUploadPanel(
       );
 
       try {
-        panel.webview.postMessage({ command: "uploadStarted", fileId: message.fileId });
+        analytics?.track("upload_started", {
+          upload_source: "file",
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
+        safePostToPanel(panel, { command: "uploadStarted", fileId: message.fileId });
 
-        const result = await uploadWithProgress(panel, message.dataUri, options, message.fileId);
+        const result = withSignedAuthenticatedUrl(
+          await uploadWithProgress(panel, message.dataUri, options, message.fileId)
+        );
         result._uploadedToFolder = folder || "(root)";
         result._originalFileName = message.fileName;
 
-        panel.webview.postMessage({
+        safePostToPanel(panel, {
           command: "uploadComplete",
           fileId: message.fileId,
           asset: result,
         });
+        analytics?.track("upload_succeeded", {
+          upload_source: "file",
+          resource_type: result.resource_type,
+          asset_type: result.type,
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
 
         vscode.commands.executeCommand("cloudinary.refresh");
       } catch (err: any) {
-        panel.webview.postMessage({
+        analytics?.track("upload_failed", {
+          upload_source: "file",
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
+        safePostToPanel(panel, {
           command: "uploadError",
           fileId: message.fileId,
           error: err.message || "Upload failed",
@@ -333,7 +528,7 @@ function createUploadPanel(
       }
 
       const options = getUploadOptions(
-        provider,
+        cloudinaryState,
         presetName,
         folder,
         message.publicId,
@@ -343,17 +538,36 @@ function createUploadPanel(
       const fileId = message.fileId || `url-${Date.now()}`;
 
       try {
-        panel.webview.postMessage({ command: "uploadStarted", fileId, fileName: message.url });
-        panel.webview.postMessage({ command: "uploadProgress", fileId, percent: 50 });
+        analytics?.track("upload_started", {
+          upload_source: "url",
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
+        safePostToPanel(panel, { command: "uploadStarted", fileId, fileName: message.url });
+        safePostToPanel(panel, { command: "uploadProgress", fileId, percent: 50 });
 
-        const result = await cloudinary.uploader.upload(message.url, options);
+        const result = withSignedAuthenticatedUrl(
+          await cloudinary.uploader.upload(message.url, options)
+        );
         result._uploadedToFolder = folder || "(root)";
         result._originalFileName = urlFileName;
 
-        panel.webview.postMessage({ command: "uploadComplete", fileId, asset: result });
+        safePostToPanel(panel, { command: "uploadComplete", fileId, asset: result });
+        analytics?.track("upload_succeeded", {
+          upload_source: "url",
+          resource_type: result.resource_type,
+          asset_type: result.type,
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
         vscode.commands.executeCommand("cloudinary.refresh");
       } catch (err: any) {
-        panel.webview.postMessage({
+        analytics?.track("upload_failed", {
+          upload_source: "url",
+          folder_selected: !!folder,
+          preset_selected: !!presetName,
+        });
+        safePostToPanel(panel, {
           command: "uploadError",
           fileId,
           error: err.message || "Upload failed",
@@ -364,28 +578,23 @@ function createUploadPanel(
 
     if (message.command === "copyToClipboard" && message.text) {
       await vscode.env.clipboard.writeText(message.text);
+      analytics?.track("copy_asset_url", { copy_type: "upload_result" });
     }
 
     if (message.command === "refreshFolders") {
-      const updatedFolders = collectFolderOptions(provider);
-      panel.webview.postMessage({ command: "updateFolders", folders: updatedFolders });
+      const updatedFolders = await collectFolderOptions(cloudinaryState);
+      safePostToPanel(panel, {
+        command: "updateFolders",
+        folderPath: currentFolderPath,
+        folders: updatedFolders,
+      });
     }
 
     if (message.command === "openAsset" && message.asset) {
       const asset = message.asset;
-      const assetType = asset.resource_type || "raw";
-
-      const optimizedUrl =
-        assetType === "raw"
-          ? cloudinary.url(asset.public_id, { resource_type: "raw", type: asset.type })
-          : cloudinary.url(asset.public_id, {
-              resource_type: assetType,
-              type: asset.type,
-              transformation: [
-                { fetch_format: assetType === "video" ? "auto:video" : "auto" },
-                { quality: "auto" },
-              ],
-            });
+      const assetType = getUploadAssetResourceType(asset);
+      const signedOriginalUrl = getSignedOriginalUrl(asset, assetType);
+      const optimizedUrl = getOptimizedUrl(asset, assetType);
 
       const filename =
         asset._originalFileName ||
@@ -393,15 +602,95 @@ function createUploadPanel(
         asset.public_id.split("/").pop() ||
         asset.public_id;
 
+      analytics?.track("asset_opened", {
+        entry_point: "upload_result",
+        resource_type: assetType,
+        asset_type: asset.type,
+      });
       vscode.commands.executeCommand("cloudinary.openAsset", {
         ...asset,
         displayType: assetType,
+        secure_url: signedOriginalUrl || asset.secure_url,
         optimized_url: optimizedUrl,
         filename,
       });
     }
   });
 
+  panel.webview.html = createWebviewDocument({
+    title: "Upload to Cloudinary",
+    webview: panel.webview,
+    extensionUri: context.extensionUri,
+    bodyContent: getUploadContent(
+      currentPreset,
+      cloudinaryState.uploadPresets,
+      currentFolderPath,
+      initialFolders
+    ),
+    bodyClass: "layout-centered",
+    additionalScripts: [uploadScriptUri],
+    inlineScript: initScript,
+  });
+
+  // Deferred load: fetch presets and folders in parallel without blocking the
+  // initial render. Posts updates to the client when each completes.
+  void (async () => {
+    // Wait for the client's "ready" handshake before posting, falling back to a
+    // short delay so a missed handshake can't hang the load indefinitely.
+    await Promise.race([
+      clientReady,
+      new Promise((resolve) => setTimeout(resolve, READY_HANDSHAKE_TIMEOUT_MS)),
+    ]);
+
+    const presetsTask = cloudinaryState
+      .fetchUploadPresets()
+      .then((presets) => {
+        safePostToPanel(panel, {
+          command: "updatePresets",
+          preset: cloudinaryState.getCurrentUploadPreset() || "",
+          presets,
+        });
+      })
+      .catch((err) => {
+        console.error("Failed to fetch upload presets:", err);
+      });
+
+    const postFolderOptions = (folders: FolderOption[]) => {
+      safePostToPanel(panel, {
+        command: "updateFolders",
+        folderPath: currentFolderPath,
+        folders,
+      });
+    };
+
+    let folderLoadSettled = false;
+    const folderLoadFallback = setTimeout(() => {
+      if (!folderLoadSettled) {
+        postFolderOptions(getInitialFolderOptions(cloudName));
+      }
+    }, FOLDER_LOAD_FALLBACK_MS);
+
+    const foldersTask = collectFolderOptions(cloudinaryState)
+      .then((folders) => {
+        folderLoadSettled = true;
+        clearTimeout(folderLoadFallback);
+        safePostToPanel(panel, {
+          command: "updateFolders",
+          folderPath: currentFolderPath,
+          folders,
+        });
+      })
+      .catch((err) => {
+        folderLoadSettled = true;
+        clearTimeout(folderLoadFallback);
+        console.error("Failed to load folders:", err);
+        // Clear the loading state and keep root usable even if the fetch failed.
+        postFolderOptions(ROOT_FOLDER_OPTIONS);
+      });
+
+    await Promise.all([presetsTask, foldersTask]);
+  })();
+
   return panel;
 }
 
@@ -410,7 +699,7 @@ function createUploadPanel(
  */
 function getUploadContent(
   currentPreset: string,
-  provider: CloudinaryTreeDataProvider,
+  uploadPresets: UploadPreset[],
   initialFolderPath: string,
   folders: FolderOption[]
 ): string {
@@ -420,7 +709,7 @@ function getUploadContent(
     )
     .join("");
 
-  const presetOptionsHtml = provider.uploadPresets
+  const presetOptionsHtml = uploadPresets
     .map(
       (p) => `<option value="${escapeHtml(p.name)}" ${p.name === currentPreset ? "selected" : ""}>${escapeHtml(p.name)} (${p.signed ? "Signed" : "Unsigned"})</option>`
     )
@@ -435,6 +724,7 @@ function getUploadContent(
           <div class="form-group">
             <label class="form-group__label" for="folderSelect">Destination Folder</label>
             <select id="folderSelect" class="select">${folderOptionsHtml}</select>
+            <div class="form-group__hint" id="folderLoadingHint">Loading folders…</div>
           </div>
         </div>
 
@@ -442,7 +732,7 @@ function getUploadContent(
           <div class="form-group">
             <div class="preset-toggle">
               <label class="form-group__label" for="presetSelect">Upload Preset <span style="opacity: 0.7; font-weight: normal;">(optional)</span></label>
-              ${provider.uploadPresets.length > 0 ? '<button class="preset-toggle__btn" id="presetDetailsToggle">Settings</button>' : ""}
+              ${uploadPresets.length > 0 ? '<button class="preset-toggle__btn" id="presetDetailsToggle">Settings</button>' : ""}
             </div>
             <select id="presetSelect" class="select">
               <option value="">No preset (signed upload)</option>
@@ -486,7 +776,7 @@ function getUploadContent(
                 <path d="M9 16h6v-6h4l-7-7-7 7h4v6zm-4 2h14v2H5v-2z"/>
               </svg>
             </div>
-            <p class="drop-zone__text">Drag & drop files here</p>
+            <p class="drop-zone__text">Hold Shift, then drag & drop files here</p>
             <p class="drop-zone__hint">— or —</p>
             <button class="btn btn--primary drop-zone__button" id="browseBtn">Browse Files</button>
             <input type="file" id="fileInput" class="drop-zone__input" multiple />
diff --git a/src/commands/viewOptions.ts b/src/commands/viewOptions.ts
index 9e82f08..6a80dbf 100644
--- a/src/commands/viewOptions.ts
+++ b/src/commands/viewOptions.ts
@@ -1,24 +1,31 @@
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { LibraryWebviewViewProvider } from "../webview/libraryView";
 
 type ResourceType = "all" | "image" | "video" | "raw";
 type SortDirection = "asc" | "desc";
+type ViewStateUpdate = {
+  resourceTypeFilter?: ResourceType;
+  sortDirection?: SortDirection;
+};
+type ViewAwareLibraryWebview = LibraryWebviewViewProvider & {
+  applyView?: (opts: ViewStateUpdate) => Thenable<void> | Promise<void>;
+};
 
 interface ViewOption {
   label: string;
   description?: string;
   kind?: vscode.QuickPickItemKind;
-  action?: () => void;
+  viewState?: ViewStateUpdate;
 }
 
 /**
  * Registers a command that opens a Quick Pick with view options (filter and sort).
  * @param context - VS Code extension context.
- * @param provider - Cloudinary tree data provider instance.
+ * @param libraryWebview - Cloudinary library webview provider.
  */
 function registerViewOptions(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  libraryWebview?: LibraryWebviewViewProvider
 ) {
   context.subscriptions.push(
     vscode.commands.registerCommand(
@@ -30,34 +37,34 @@ function registerViewOptions(
           {
             label: "$(file) All Types",
             description: "Show all asset types",
-            action: () => provider.refresh({ resourceTypeFilter: "all" as ResourceType }),
+            viewState: { resourceTypeFilter: "all" as ResourceType },
           },
           {
             label: "$(file-media) Images Only",
             description: "Show only images",
-            action: () => provider.refresh({ resourceTypeFilter: "image" as ResourceType }),
+            viewState: { resourceTypeFilter: "image" as ResourceType },
           },
           {
             label: "$(device-camera-video) Videos Only",
             description: "Show only videos",
-            action: () => provider.refresh({ resourceTypeFilter: "video" as ResourceType }),
+            viewState: { resourceTypeFilter: "video" as ResourceType },
           },
           {
             label: "$(file-binary) Raw Files Only",
             description: "Show only raw files",
-            action: () => provider.refresh({ resourceTypeFilter: "raw" as ResourceType }),
+            viewState: { resourceTypeFilter: "raw" as ResourceType },
           },
           // Sort section
           { label: "Sort Order", kind: vscode.QuickPickItemKind.Separator },
           {
             label: "$(arrow-down) Newest First",
             description: "Most recently uploaded assets first",
-            action: () => provider.refresh({ sortDirection: "desc" as SortDirection }),
+            viewState: { sortDirection: "desc" as SortDirection },
           },
           {
             label: "$(arrow-up) Oldest First",
             description: "Oldest uploaded assets first",
-            action: () => provider.refresh({ sortDirection: "asc" as SortDirection }),
+            viewState: { sortDirection: "asc" as SortDirection },
           },
         ];
 
@@ -66,8 +73,8 @@ function registerViewOptions(
           matchOnDescription: true,
         });
 
-        if (selected && selected.action) {
-          selected.action();
+        if (selected?.viewState) {
+          await (libraryWebview as ViewAwareLibraryWebview | undefined)?.applyView?.(selected.viewState);
         }
       }
     )
diff --git a/src/commands/welcomeScreen.ts b/src/commands/welcomeScreen.ts
index c32a18f..3b02bbf 100644
--- a/src/commands/welcomeScreen.ts
+++ b/src/commands/welcomeScreen.ts
@@ -1,32 +1,59 @@
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { CloudinaryService } from "../cloudinary/cloudinaryService";
 import {
   createWebviewDocument,
   getScriptUri,
 } from "../webview/webviewUtils";
 import { escapeHtml } from "../webview/utils/helpers";
+import { getConnectionStatus } from "../config/connectionStatus";
+
+type WelcomeScreenCloudinaryState = Pick<
+  CloudinaryService,
+  "cloudName" | "apiKey" | "apiSecret" | "credentialsValid"
+>;
+
+let welcomePanel: vscode.WebviewPanel | undefined;
+let welcomeContext: vscode.ExtensionContext | undefined;
+let welcomeCloudinaryState: WelcomeScreenCloudinaryState | undefined;
 
 /**
  * Registers the welcome screen command.
  */
 function registerWelcomeScreen(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryState: WelcomeScreenCloudinaryState
 ) {
+  welcomeContext = context;
+  welcomeCloudinaryState = cloudinaryState;
+
   context.subscriptions.push(
     vscode.commands.registerCommand("cloudinary.openWelcomeScreen", () => {
-      createWelcomePanel(context, provider);
+      createWelcomePanel(context, cloudinaryState);
     })
   );
 }
 
+export function refreshWelcomePanel(): void {
+  if (!welcomePanel || !welcomeContext || !welcomeCloudinaryState) {
+    return;
+  }
+
+  renderWelcomePanel(welcomePanel, welcomeContext, welcomeCloudinaryState);
+}
+
 /**
  * Creates the welcome screen webview panel.
  */
 function createWelcomePanel(
   context: vscode.ExtensionContext,
-  provider: CloudinaryTreeDataProvider
+  cloudinaryState: WelcomeScreenCloudinaryState
 ): vscode.WebviewPanel {
+  if (welcomePanel) {
+    welcomePanel.reveal(vscode.ViewColumn.One);
+    renderWelcomePanel(welcomePanel, context, cloudinaryState);
+    return welcomePanel;
+  }
+
   const panel = vscode.window.createWebviewPanel(
     "cloudinaryWelcome",
     "Welcome to Cloudinary",
@@ -39,6 +66,7 @@ function createWelcomePanel(
       ],
     }
   );
+  welcomePanel = panel;
 
   panel.iconPath = vscode.Uri.joinPath(
     context.extensionUri,
@@ -46,18 +74,10 @@ function createWelcomePanel(
     "cloudinary_icon_blue.png"
   );
 
-  const welcomeScriptUri = getScriptUri(
-    panel.webview,
-    context.extensionUri,
-    "welcome.js"
-  );
+  renderWelcomePanel(panel, context, cloudinaryState);
 
-  panel.webview.html = createWebviewDocument({
-    title: "Welcome to Cloudinary",
-    webview: panel.webview,
-    extensionUri: context.extensionUri,
-    bodyContent: getWelcomeContent(provider),
-    additionalScripts: [welcomeScriptUri],
+  panel.onDidDispose(() => {
+    welcomePanel = undefined;
   });
 
   panel.webview.onDidReceiveMessage((message: { command: string; data?: string; text?: string }) => {
@@ -77,8 +97,8 @@ function createWelcomePanel(
           vscode.env.openExternal(vscode.Uri.parse(message.data));
         }
         break;
-      case "focusTreeView":
-        vscode.commands.executeCommand("workbench.view.extension.cloudinary");
+      case "focusDashboard":
+        vscode.commands.executeCommand("cloudinary.showHomescreen");
         break;
     }
   });
@@ -86,12 +106,60 @@ function createWelcomePanel(
   return panel;
 }
 
+function renderWelcomePanel(
+  panel: vscode.WebviewPanel,
+  context: vscode.ExtensionContext,
+  cloudinaryState: WelcomeScreenCloudinaryState
+): void {
+  const welcomeScriptUri = getScriptUri(
+    panel.webview,
+    context.extensionUri,
+    "welcome.js"
+  );
+
+  panel.webview.html = createWebviewDocument({
+    title: "Welcome to Cloudinary",
+    webview: panel.webview,
+    extensionUri: context.extensionUri,
+    bodyContent: getWelcomeContent(cloudinaryState),
+    additionalScripts: [welcomeScriptUri],
+  });
+}
+
 /**
  * Generates the welcome screen body content.
  */
-function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
-  const hasConfig = !!(provider.cloudName && provider.apiKey);
-  const cloudName = escapeHtml(provider.cloudName || "");
+function getWelcomeContent(cloudinaryState: WelcomeScreenCloudinaryState): string {
+  const status = getConnectionStatus({
+    cloudName: cloudinaryState.cloudName,
+    apiKey: cloudinaryState.apiKey,
+    apiSecret: cloudinaryState.apiSecret,
+    credentialsValid: cloudinaryState.credentialsValid,
+  });
+  const isConnected = status === "connected";
+  const isChecking = status === "checking";
+  const isInvalidCredentials = status === "invalidCredentials";
+  const hasCredentials = !!(cloudinaryState.cloudName && cloudinaryState.apiKey && cloudinaryState.apiSecret);
+  const cloudName = escapeHtml(cloudinaryState.cloudName || "");
+  const statusClass = isConnected ? "ok" : isChecking ? "neutral" : "warn";
+  const statusLabel = isConnected
+    ? `Connected to ${cloudName}`
+    : isChecking
+      ? `Checking ${cloudName || "credentials"}`
+      : isInvalidCredentials
+        ? "Cloudinary credentials are invalid"
+      : hasCredentials
+        ? "Credentials need attention"
+        : "No credentials configured";
+  const statusDetail = isConnected
+    ? "Your environment is ready. Open the dashboard to explore your media."
+    : isChecking
+      ? "Validating your Cloudinary credentials before opening the dashboard."
+      : isInvalidCredentials
+        ? "Check that the cloud name, API key, and API secret belong to the same product environment."
+      : hasCredentials
+        ? "Update your Cloudinary API credentials to connect."
+        : "Add your Cloudinary API credentials to get started.";
 
   return `
   <style>
@@ -154,11 +222,13 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
       animation: wg-in 0.3s ease both;
     }
     .wg-status--ok  { background: rgba(74,222,128,0.07);  border-color: rgba(74,222,128,0.22); }
+    .wg-status--neutral{ background: rgba(96,165,250,0.07); border-color: rgba(96,165,250,0.22); }
     .wg-status--warn{ background: rgba(251,191,36,0.07);  border-color: rgba(251,191,36,0.22); }
     .wg-status-dot {
       width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0;
     }
     .wg-status--ok   .wg-status-dot { background: #4ade80; box-shadow: 0 0 7px rgba(74,222,128,0.65); }
+    .wg-status--neutral .wg-status-dot { background: #60a5fa; box-shadow: 0 0 7px rgba(96,165,250,0.55); }
     .wg-status--warn .wg-status-dot { background: #fbbf24; box-shadow: 0 0 7px rgba(251,191,36,0.65); }
     .wg-status-body { flex: 1; }
     .wg-status-label  { font-size: 13px; font-weight: 600; }
@@ -340,16 +410,16 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
     <div class="wg-body">
 
       <!-- ── Connection status ── -->
-      <div class="wg-status wg-status--${hasConfig ? "ok" : "warn"}">
+      <div class="wg-status wg-status--${statusClass}">
         <div class="wg-status-dot"></div>
         <div class="wg-status-body">
-          <div class="wg-status-label">${hasConfig ? `Connected to ${cloudName}` : "No credentials configured"}</div>
-          <div class="wg-status-detail">${hasConfig ? "Your environment is ready. Open the dashboard to explore your media." : "Add your Cloudinary API credentials to get started."}</div>
+          <div class="wg-status-label">${statusLabel}</div>
+          <div class="wg-status-detail">${statusDetail}</div>
         </div>
-        ${hasConfig
-          ? `<button class="wg-btn wg-btn--ghost" onclick="focusTreeView()">Open Dashboard →</button>`
-          : `<button class="wg-btn wg-btn--primary" onclick="openGlobalConfig()">Configure →</button>`
-        }
+        ${isConnected
+      ? `<button class="wg-btn wg-btn--ghost" data-welcome-action="focusDashboard">Open Dashboard →</button>`
+      : `<button class="wg-btn wg-btn--primary" data-welcome-action="openGlobalConfig">Configure →</button>`
+    }
       </div>
 
       <!-- ── Setup steps ── -->
@@ -357,11 +427,11 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
       <div class="wg-steps">
 
         <div class="wg-step">
-          <div class="wg-step-num ${hasConfig ? "wg-step-num--done" : ""}">${hasConfig ? "✓" : "1"}</div>
+          <div class="wg-step-num ${isConnected ? "wg-step-num--done" : ""}">${isConnected ? "✓" : "1"}</div>
           <div class="wg-step-body">
             <div class="wg-step-title">
               Connect your Cloudinary account
-              ${hasConfig ? '<span class="wg-badge">✓ Done</span>' : ""}
+              ${isConnected ? '<span class="wg-badge">✓ Done</span>' : ""}
             </div>
             <p class="wg-step-desc">
               Add your Cloud Name, API Key, and API Secret to
@@ -369,8 +439,8 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
               Credentials are never stored in VS Code settings — they stay in a local file you control.
             </p>
             <div class="wg-step-actions">
-              <button class="wg-btn wg-btn--primary" onclick="openGlobalConfig()">${hasConfig ? "View Config File" : "Open Config File"}</button>
-              <button class="wg-btn wg-btn--ghost" onclick="openExternal('https://console.cloudinary.com/settings/api-keys')">Get API Keys</button>
+              <button class="wg-btn wg-btn--primary" data-welcome-action="openGlobalConfig">${hasCredentials ? "View Config File" : "Open Config File"}</button>
+              <button class="wg-btn wg-btn--ghost" data-welcome-action="openExternal" data-url="https://console.cloudinary.com/settings/api-keys">Get API Keys</button>
             </div>
           </div>
         </div>
@@ -381,7 +451,7 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
             <div class="wg-step-title">Explore the Dashboard</div>
             <p class="wg-step-desc">The Cloudinary sidebar gives you instant access to your media library, upload tools, and AI integrations — all without leaving your editor. Open it from the activity bar on the left.</p>
             <div class="wg-step-actions">
-              <button class="wg-btn wg-btn--primary" onclick="focusTreeView()">Open Dashboard</button>
+              <button class="wg-btn wg-btn--primary" data-welcome-action="focusDashboard">Open Dashboard</button>
             </div>
           </div>
         </div>
@@ -390,9 +460,9 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
           <div class="wg-step-num">3</div>
           <div class="wg-step-body">
             <div class="wg-step-title">Browse &amp; manage your media</div>
-            <p class="wg-step-desc">Search and explore assets in the tree view. Preview images and videos, copy delivery URLs, upload new files with drag-and-drop, and manage transformations — all from VS Code.</p>
+            <p class="wg-step-desc">Search and explore assets in the media library. Preview images and videos, copy delivery URLs, upload new files with drag-and-drop, and manage transformations — all from VS Code.</p>
             <div class="wg-step-actions">
-              <button class="wg-btn wg-btn--ghost" onclick="openExternal('https://cloudinary.com/documentation/how_to_integrate_cloudinary')">View Documentation</button>
+              <button class="wg-btn wg-btn--ghost" data-welcome-action="openExternal" data-url="https://cloudinary.com/documentation/how_to_integrate_cloudinary">View Documentation</button>
             </div>
           </div>
         </div>
@@ -400,7 +470,7 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
       </div>
 
       <!-- ── Config format ── -->
-      <details class="wg-config"${!hasConfig ? " open" : ""}>
+      <details class="wg-config"${!hasCredentials ? " open" : ""}>
         <summary>Configuration file format</summary>
         <div class="wg-config-body">
           <p class="wg-config-note">
@@ -408,7 +478,7 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
             The cloud name is the key. You can define multiple environments.
           </p>
           <div class="wg-code">
-            <button class="wg-btn wg-btn--ghost wg-btn--sm wg-code-copy" onclick="copyToClipboard(getConfigExample(), this)">Copy</button>
+            <button class="wg-btn wg-btn--ghost wg-btn--sm wg-code-copy" data-welcome-action="copyConfigExample">Copy</button>
             <pre>{
   "your-cloud-name": {
     "apiKey": "your-api-key",
@@ -418,7 +488,7 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
           </div>
           <p class="wg-config-note" style="margin-top:12px;margin-bottom:0;">
             Find your credentials at
-            <span class="wg-link" onclick="openExternal('https://console.cloudinary.com/settings/api-keys')">Console → Settings → API Keys</span>.
+            <span class="wg-link" data-welcome-action="openExternal" data-url="https://console.cloudinary.com/settings/api-keys">Console → Settings → API Keys</span>.
             You can optionally include <span class="wg-mono">uploadPreset</span> for upload configuration.
           </p>
         </div>
@@ -430,32 +500,32 @@ function getWelcomeContent(provider: CloudinaryTreeDataProvider): string {
       <div class="wg-resources">
         <div class="wg-section-label">Resources</div>
         <div class="wg-res-grid">
-          <div class="wg-res-card" onclick="openExternal('https://cloudinary.com/documentation')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://cloudinary.com/documentation">
             <div class="wg-res-icon">📖</div>
             <div class="wg-res-title">Documentation</div>
             <div class="wg-res-desc">Guides, API reference &amp; tutorials</div>
           </div>
-          <div class="wg-res-card" onclick="openExternal('https://console.cloudinary.com')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://console.cloudinary.com">
             <div class="wg-res-icon">🖥</div>
             <div class="wg-res-title">Console</div>
             <div class="wg-res-desc">Manage your media &amp; settings online</div>
           </div>
-          <div class="wg-res-card" onclick="openExternal('https://cloudinary.com/documentation/upload_images')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://cloudinary.com/documentation/upload_images">
             <div class="wg-res-icon">⬆</div>
             <div class="wg-res-title">Upload Guide</div>
             <div class="wg-res-desc">Learn to upload &amp; organize assets</div>
           </div>
-          <div class="wg-res-card" onclick="openExternal('https://cloudinary.com/documentation/image_transformations')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://cloudinary.com/documentation/image_transformations">
             <div class="wg-res-icon">✨</div>
             <div class="wg-res-title">Transformations</div>
             <div class="wg-res-desc">Resize, crop &amp; optimize media</div>
           </div>
-          <div class="wg-res-card" onclick="openExternal('https://support.cloudinary.com')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://support.cloudinary.com">
             <div class="wg-res-icon">💬</div>
             <div class="wg-res-title">Support</div>
             <div class="wg-res-desc">Get help from the Cloudinary team</div>
           </div>
-          <div class="wg-res-card" onclick="openExternal('https://cloudinary.com/users/register_free')">
+          <div class="wg-res-card" data-welcome-action="openExternal" data-url="https://cloudinary.com/users/register_free">
             <div class="wg-res-icon">🌱</div>
             <div class="wg-res-title">Free Account</div>
             <div class="wg-res-desc">New to Cloudinary? Sign up free</div>
diff --git a/src/config/configUtils.ts b/src/config/configUtils.ts
index c89a988..f6f197e 100644
--- a/src/config/configUtils.ts
+++ b/src/config/configUtils.ts
@@ -9,6 +9,13 @@ export interface CloudinaryEnvironment {
   uploadPreset?: string;  // Optional: Default upload preset to use (signed uploads work without it)
 }
 
+export function hasCompleteEnvironment(
+  cloudName: string | null | undefined,
+  env: Partial<CloudinaryEnvironment> | null | undefined
+): env is CloudinaryEnvironment {
+  return !!cloudName?.trim() && !!env?.apiKey?.trim() && !!env?.apiSecret?.trim();
+}
+
 /**
  * Checks if the provided credentials are placeholder values.
  * @param cloudName - The cloud name to check.
@@ -68,7 +75,7 @@ export function getGlobalConfigPath(): string {
     fs.writeFileSync(envPath, templateContent, 'utf-8');
 
     vscode.window.showInformationMessage(
-      '✅ Created global Cloudinary config at ~/.cloudinary/environments.json'
+      'Created global Cloudinary config at ~/.cloudinary/environments.json'
     );
   }
 
@@ -88,7 +95,7 @@ export async function loadEnvironments(): Promise<Record<string, CloudinaryEnvir
     globalEnvs = JSON.parse(raw);
   } catch (err: any) {
     vscode.window.showErrorMessage(
-      `❌ Failed to read global Cloudinary config: ${err.message}`
+      `Failed to read global Cloudinary config: ${err.message}`
     );
   }
 
@@ -105,9 +112,9 @@ export async function loadEnvironments(): Promise<Record<string, CloudinaryEnvir
     }
   } catch (err: any) {
     vscode.window.showErrorMessage(
-      `❌ Failed to read workspace Cloudinary config: ${err.message}`
+      `Failed to read workspace Cloudinary config: ${err.message}`
     );
   }
 
   return globalEnvs;
-}
\ No newline at end of file
+}
diff --git a/src/config/connectionStatus.ts b/src/config/connectionStatus.ts
new file mode 100644
index 0000000..e4f44d3
--- /dev/null
+++ b/src/config/connectionStatus.ts
@@ -0,0 +1,40 @@
+/** Inputs needed to decide the homescreen connection status. */
+export interface ConnectionStatusInput {
+  cloudName: string | null;
+  apiKey: string | null;
+  apiSecret: string | null;
+  /** `true` validated OK, `false` rejected by API, `undefined` not yet known. */
+  credentialsValid: boolean | undefined;
+}
+
+/**
+ * - `connected`: credentials present and validated against the API.
+ * - `setupNeeded`: credentials missing or incomplete.
+ * - `invalidCredentials`: credentials are present but actively rejected (e.g. 401/403).
+ * - `checking`: credentials present but not yet validated (or validation could
+ *   not complete, e.g. offline). Deliberately neither "Connected" nor "Setup
+ *   needed" so we never claim a valid cloud is broken, nor claim an unverified
+ *   (possibly invalid) cloud is connected.
+ */
+export type ConnectionStatus = "connected" | "setupNeeded" | "invalidCredentials" | "checking";
+
+/**
+ * Decides the homescreen connection status from credentials + validation state.
+ *
+ * A folder-mode cache is keyed by cloud name, not by the API key/secret, so it
+ * must never be allowed to imply "connected"; only an explicit
+ * `credentialsValid === true` (a successful live validation) does that.
+ */
+export function getConnectionStatus(input: ConnectionStatusInput): ConnectionStatus {
+  const hasCredentials = !!(input.cloudName && input.apiKey && input.apiSecret);
+  if (!hasCredentials) {
+    return "setupNeeded";
+  }
+  if (input.credentialsValid === true) {
+    return "connected";
+  }
+  if (input.credentialsValid === false) {
+    return "invalidCredentials";
+  }
+  return "checking";
+}
diff --git a/src/config/detectFolderMode.ts b/src/config/detectFolderMode.ts
index 5537b3d..5fe70ce 100644
--- a/src/config/detectFolderMode.ts
+++ b/src/config/detectFolderMode.ts
@@ -1,31 +1,80 @@
 import * as vscode from 'vscode';
 import { generateUserAgent } from '../utils/userAgent';
 import { isPlaceholderConfig } from './configUtils';
+import type { CachedFolderMode } from './folderModeCache';
+
+export type FolderModeOutcome = 'success' | 'error' | 'skipped';
+
+/**
+ * Result of a folder-mode detection attempt.
+ * - `success`: credentials were accepted by the API (dynamicFolders is meaningful).
+ * - `error`: the API rejected the credentials or could not be reached.
+ * - `skipped`: detection was not attempted (missing or placeholder credentials).
+ */
+export interface FolderModeResult {
+  dynamicFolders: boolean;
+  outcome: FolderModeOutcome;
+  status?: number;
+  errorReason?: string;
+}
+
+export interface ResolvedFolderModeState {
+  dynamicFolders: boolean;
+  credentialsValid: boolean | undefined;
+}
 
 /**
- * Detects if the cloud supports dynamic folders by making a request to the root folder API.
+ * Converts a live detection result into extension state.
+ *
+ * A cached folder mode is only a fallback for UI folder-mode continuity. It is
+ * keyed by cloud name, not credentials, so it must never be treated as proof
+ * that the current API key and secret are valid.
+ */
+export function resolveFolderModeState(
+  result: FolderModeResult,
+  cached?: CachedFolderMode
+): ResolvedFolderModeState {
+  if (result.outcome === 'success') {
+    return { dynamicFolders: result.dynamicFolders, credentialsValid: true };
+  }
+
+  if (result.errorReason === 'unauthorized') {
+    return { dynamicFolders: result.dynamicFolders, credentialsValid: false };
+  }
+
+  if (cached) {
+    return { dynamicFolders: cached.value, credentialsValid: undefined };
+  }
+
+  return { dynamicFolders: result.dynamicFolders, credentialsValid: undefined };
+}
+
+/**
+ * Detects whether the product environment uses dynamic or fixed folders.
+ * The returned result also reflects whether the configured credentials are valid, so callers
+ * can report configuration success/error analytics.
  * @param cloudName - The cloud name.
  * @param apiKey - The API key.
  * @param apiSecret - The API secret.
- * @returns True if dynamic folders are supported, false otherwise.
+ * @returns A {@link FolderModeResult} describing the folder mode and validation outcome.
  */
-export default async function detectFolderMode(
+export async function detectFolderModeResult(
   cloudName: string,
   apiKey: string,
   apiSecret: string
-): Promise<boolean> {
+): Promise<FolderModeResult> {
   if (!cloudName || !apiKey || !apiSecret) {
-    vscode.window.showErrorMessage("❌ Cloud name, API key, and API secret are required.");
-    return false;
+    vscode.window.showErrorMessage("Cloud name, API key, and API secret are required.");
+    return { dynamicFolders: false, outcome: 'skipped', errorReason: 'missing_credentials' };
   }
 
   // Don't make API calls with placeholder credentials
   if (isPlaceholderConfig(cloudName, apiKey, apiSecret)) {
-    return false;
+    return { dynamicFolders: false, outcome: 'skipped', errorReason: 'placeholder' };
   }
 
   const authHeader = `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString('base64')}`;
-  const url = `https://api.cloudinary.com/v1_1/${cloudName}/folders`;
+  const url = `https://api.cloudinary.com/v1_1/${cloudName}/config?settings=true`;
 
   try {
     const response = await fetch(url, {
@@ -36,15 +85,37 @@ export default async function detectFolderMode(
     });
 
     if (response.status === 200) {
-      return true; // Dynamic folders are supported
-    } else if (response.status === 420) {
-      return false; // Dynamic folders are not supported (fixed folder mode)
+      const body = await response.json().catch(() => null);
+      const folderMode = body?.settings?.folder_mode;
+      if (folderMode === 'dynamic' || folderMode === 'fixed') {
+        return { dynamicFolders: folderMode === 'dynamic', outcome: 'success', status: 200 };
+      }
+
+      return {
+        dynamicFolders: false,
+        outcome: 'error',
+        status: response.status,
+        errorReason: 'unexpected_response',
+      };
+    } else if (response.status === 401 || response.status === 403) {
+      // Credentials were rejected
+      return {
+        dynamicFolders: false,
+        outcome: 'error',
+        status: response.status,
+        errorReason: 'unauthorized',
+      };
     } else {
       // Fallback to fixed folder mode for other errors
-      return false;
+      return {
+        dynamicFolders: false,
+        outcome: 'error',
+        status: response.status,
+        errorReason: 'unexpected_status',
+      };
     }
   } catch (error) {
     // Default to fixed folder mode if the request fails
-    return false;
+    return { dynamicFolders: false, outcome: 'error', errorReason: 'network_error' };
   }
-}
\ No newline at end of file
+}
diff --git a/src/config/folderModeCache.ts b/src/config/folderModeCache.ts
new file mode 100644
index 0000000..447fbff
--- /dev/null
+++ b/src/config/folderModeCache.ts
@@ -0,0 +1,61 @@
+import * as vscode from "vscode";
+
+/**
+ * Timestamped folder-mode cache entry stored in globalState.
+ *
+ * The folder mode is re-detected on every activation/save/switch (detection also
+ * validates the live credentials), so this cache is only a fallback that keeps a
+ * last-known folder mode for UI continuity when a detection attempt fails for a
+ * non-credential reason (e.g. the network is down). `detectedAt` records when it
+ * was last confirmed.
+ */
+export interface CachedFolderMode {
+  value: boolean;
+  detectedAt: number;
+}
+
+/** Returns the globalState key under which a cloud's folder mode is cached. */
+export function folderModeCacheKey(cloudName: string): string {
+  return `cloudinary.dynamicFolders.${cloudName}`;
+}
+
+/**
+ * Reads the cached folder-mode entry for a cloud.
+ *
+ * Returns the entry only when it is a timestamped object. Legacy plain-boolean
+ * entries (written before the cache carried a timestamp) are ignored so installs
+ * stuck on an outdated mode re-validate and self-heal. No TTL check is applied
+ * here — callers decide whether they want a still-fresh value or a last-known
+ * value to fall back on after a failed detection.
+ */
+export function readFolderModeCache(
+  storage: vscode.Memento,
+  cloudName: string
+): CachedFolderMode | undefined {
+  const cached = storage.get(folderModeCacheKey(cloudName)) as
+    | CachedFolderMode
+    | boolean
+    | undefined;
+  if (
+    cached &&
+    typeof cached === "object" &&
+    typeof cached.value === "boolean" &&
+    Number.isFinite(cached.detectedAt)
+  ) {
+    return cached;
+  }
+  return undefined;
+}
+
+/** Persists a freshly detected folder mode with the current timestamp. */
+export function writeFolderModeCache(
+  storage: vscode.Memento,
+  cloudName: string,
+  value: boolean,
+  now: number = Date.now()
+): Thenable<void> {
+  return storage.update(folderModeCacheKey(cloudName), {
+    value,
+    detectedAt: now,
+  } satisfies CachedFolderMode);
+}
diff --git a/src/extension.ts b/src/extension.ts
index ab10f7d..907a1c5 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -1,26 +1,53 @@
 import * as vscode from "vscode";
 import * as path from "path";
+import * as fs from "fs";
 import {
   getGlobalConfigPath,
+  hasCompleteEnvironment,
   loadEnvironments,
   CloudinaryEnvironment,
   isPlaceholderConfig,
 } from "./config/configUtils";
-import detectFolderMode from "./config/detectFolderMode";
+import { detectFolderModeResult, resolveFolderModeState } from "./config/detectFolderMode";
+import {
+  readFolderModeCache,
+  writeFolderModeCache,
+} from "./config/folderModeCache";
+import { trackConfigValidation } from "./analytics/trackConfigValidation";
 import { registerAllCommands } from "./commands/registerCommands";
-import { CloudinaryTreeDataProvider } from "./tree/treeDataProvider";
+import { CloudinaryService, Credentials } from "./cloudinary/cloudinaryService";
+import { createCloudinarySdkAdapter } from "./cloudinary/cloudinarySdkAdapter";
 import { v2 as cloudinary } from "cloudinary";
+import packageJson from "../package.json";
+import { AnalyticsService } from "./analytics/analyticsService";
 import { generateUserAgent } from "./utils/userAgent";
 import { HomescreenViewProvider } from "./webview/homescreenView";
+import { LibraryWebviewViewProvider } from "./webview/libraryView";
+import { DocsAiViewProvider } from "./webview/docsAiView";
 import { resetUploadPanel } from "./commands/uploadWidget";
 import { resetAllPreviewPanels } from "./commands/previewAsset";
+import { detectEditorPlatform } from "./aiToolsService";
+import { refreshWelcomePanel } from "./commands/welcomeScreen";
 
 let statusBar: vscode.StatusBarItem;
 
 /**
  * Returns the status bar text with cloud name and folder mode indicator.
  */
-function getStatusBarText(cloudName: string, dynamicFolders: boolean): string {
+function getStatusBarText(
+  cloudName: string,
+  dynamicFolders: boolean,
+  credentialsValid?: boolean
+): string {
+  // Rejected credentials: warn and drop the folder-mode chip (it isn't trustworthy).
+  if (credentialsValid === false) {
+    return `$(warning) ${cloudName}: credentials invalid`;
+  }
+  // Not yet validated (or unverifiable, e.g. offline): show the cloud without
+  // asserting a folder mode we haven't confirmed.
+  if (credentialsValid === undefined) {
+    return `$(cloud) ${cloudName}`;
+  }
   const folderMode = dynamicFolders ? "Dynamic" : "Fixed";
   return `$(cloud) ${cloudName} $(folder) ${folderMode}`;
 }
@@ -28,7 +55,13 @@ function getStatusBarText(cloudName: string, dynamicFolders: boolean): string {
 /**
  * Returns the status bar tooltip with folder mode explanation.
  */
-function getStatusBarTooltip(dynamicFolders: boolean): string {
+function getStatusBarTooltip(dynamicFolders: boolean, credentialsValid?: boolean): string {
+  if (credentialsValid === false) {
+    return "Cloudinary credentials are invalid or unauthorized.\n\nClick to switch environment, or update your config.";
+  }
+  if (credentialsValid === undefined) {
+    return "Click to switch Cloudinary environment";
+  }
   const modeDescription = dynamicFolders
     ? "Dynamic Folders: Assets can be organized independently of their public ID"
     : "Fixed Folders: Asset folder is determined by public ID path";
@@ -40,13 +73,40 @@ function getStatusBarTooltip(dynamicFolders: boolean): string {
  * @param context - Extension context provided by VS Code.
  */
 export async function activate(context: vscode.ExtensionContext) {
-  const cloudinaryProvider = new CloudinaryTreeDataProvider();
+  const cloudinaryService = new CloudinaryService(createCloudinarySdkAdapter());
+  const analytics = new AnalyticsService({
+    extensionVersion: packageJson.version,
+    storage: context.globalState,
+    getCloudName: () => cloudinaryService.cloudName,
+    getDebugId: () => process.env.CLOUDINARY_ANALYTICS_DEBUG_ID,
+    getIdePlatform: detectEditorPlatform,
+  });
+  analytics.track("extension_activated");
 
   // Set initial view to homescreen
   vscode.commands.executeCommand("setContext", "cloudinary.activeView", "homescreen");
 
+  const libraryWebviewProvider = new LibraryWebviewViewProvider(
+    context.extensionUri,
+    cloudinaryService,
+    analytics
+  );
+  context.subscriptions.push(
+    vscode.window.registerWebviewViewProvider(
+      LibraryWebviewViewProvider.viewType,
+      libraryWebviewProvider,
+      { webviewOptions: { retainContextWhenHidden: true } }
+    )
+  );
+
   // Register homescreen sidebar view
-  const homescreenProvider = new HomescreenViewProvider(context.extensionUri, cloudinaryProvider);
+  const homescreenProvider = new HomescreenViewProvider(
+    context.extensionUri,
+    cloudinaryService,
+    context.globalState,
+    libraryWebviewProvider,
+    analytics
+  );
   context.subscriptions.push(
     vscode.window.registerWebviewViewProvider(
       HomescreenViewProvider.viewType,
@@ -55,189 +115,344 @@ export async function activate(context: vscode.ExtensionContext) {
     )
   );
 
-  // Refresh all open webviews when the active environment changes.
+  const docsAiProvider = new DocsAiViewProvider(
+    context.extensionUri,
+    context.globalState,
+    analytics,
+    (recentConversations) => homescreenProvider.setDocsAiRecentConversations(recentConversations)
+  );
+  homescreenProvider.setDocsAiRecentConversationsRefresh(() => docsAiProvider.requestRecentConversations());
   context.subscriptions.push(
-    cloudinaryProvider.onDidChangeEnvironment(() => {
-      homescreenProvider.refresh();
-      resetUploadPanel();
-      resetAllPreviewPanels();
+    vscode.window.registerWebviewViewProvider(
+      DocsAiViewProvider.viewType,
+      docsAiProvider,
+      { webviewOptions: { retainContextWhenHidden: true } }
+    ),
+    vscode.commands.registerCommand("cloudinary.docsAi.refresh", () => {
+      docsAiProvider.refresh();
     })
   );
 
-  // Check if this is the first run of the extension
-  const isFirstRun = context.globalState.get('cloudinary.firstRun', true);
-
-
-  if (isFirstRun) {
-    // Mark as no longer first run
-    context.globalState.update('cloudinary.firstRun', false);
-
-    // Show welcome screen automatically on first install
-    vscode.commands.executeCommand("cloudinary.openWelcomeScreen");
-  }
-
-  const environments = await loadEnvironments();
-  const firstCloudName = Object.keys(environments)[0];
-  const selectedEnv: CloudinaryEnvironment = environments[firstCloudName];
-
-  if (!selectedEnv) {
-    vscode.window.showErrorMessage(
-      "❌ No Cloudinary environment found in config."
-    );
-    return;
-  }
-
-  // Check if credentials are placeholder values
-  if (isPlaceholderConfig(firstCloudName, selectedEnv.apiKey, selectedEnv.apiSecret)) {
-    // Initialize status bar with placeholder indicator (no popup message to avoid scaring new users)
-    statusBar = vscode.window.createStatusBarItem(
-      vscode.StatusBarAlignment.Right,
-      500
-    );
-    statusBar.text = `$(warning) Cloudinary: Not Configured`;
-    statusBar.tooltip = "Click to configure Cloudinary credentials";
-    statusBar.command = "cloudinary.openGlobalConfig";
-    statusBar.show();
-    context.subscriptions.push(statusBar);
-    
-    // Still register the tree view but don't make API calls
-    vscode.window.registerTreeDataProvider(
-      "cloudinaryMediaLibrary",
-      cloudinaryProvider
-    );
-    registerAllCommands(context, cloudinaryProvider, statusBar, homescreenProvider);
-    return;
-  }
+  context.subscriptions.push(
+    vscode.workspace.onDidChangeConfiguration((event) => {
+      if (event.affectsConfiguration("cloudinary.docsAi.apiBase")) {
+        docsAiProvider.refresh();
+      }
+    })
+  );
 
-  cloudinaryProvider.cloudName = firstCloudName;
-  cloudinaryProvider.apiKey = selectedEnv.apiKey;
-  cloudinaryProvider.apiSecret = selectedEnv.apiSecret;
-  cloudinaryProvider.uploadPreset = selectedEnv.uploadPreset || null;
+  const refreshEnvironmentViews = async (): Promise<void> => {
+    homescreenProvider.refresh();
+    refreshWelcomePanel();
+    resetUploadPanel();
+    resetAllPreviewPanels();
+    await libraryWebviewProvider.envChanged();
+  };
+
+  const updateCloudinaryConfig = (
+    cloudName: string,
+    apiKey: string,
+    apiSecret: string
+  ): void => {
+    (cloudinary.utils as any).userPlatform = generateUserAgent();
+    cloudinary.config({
+      cloud_name: cloudName,
+      api_key: apiKey,
+      api_secret: apiSecret,
+    });
+  };
+
+  const resolveDynamicFolders = async (
+    cloudName: string,
+    apiKey: string,
+    apiSecret: string,
+    entryPoint: string,
+    options: { force?: boolean } = {}
+  ): Promise<{ dynamicFolders: boolean; credentialsValid: boolean | undefined }> => {
+    // Cached entry (any age). Legacy plain-boolean entries are ignored so
+    // installs stuck on an outdated mode re-validate and self-heal.
+    const cached = readFolderModeCache(context.globalState, cloudName);
+
+    // Fresh validation: exercise the current credentials and report success/error
+    // once. A folder-mode cache is keyed only by cloud name, so it can provide a
+    // last-known folder mode but must never certify that the current API key and
+    // secret are valid.
+    const result = await detectFolderModeResult(cloudName, apiKey, apiSecret);
+    trackConfigValidation(analytics, result, entryPoint);
+
+    if (result.outcome === "success") {
+      await writeFolderModeCache(context.globalState, cloudName, result.dynamicFolders);
+    }
+    return resolveFolderModeState(result, cached);
+  };
+
+  const environmentTarget: Pick<
+    CloudinaryService,
+    "cloudName" | "apiKey" | "apiSecret" | "uploadPreset" | "dynamicFolders" | "credentialsValid"
+  > & {
+    setCredentials: (creds: Credentials) => void;
+  } = {
+    get cloudName() {
+      return cloudinaryService.cloudName;
+    },
+    set cloudName(value: string | null) {
+      cloudinaryService.cloudName = value;
+    },
+    get apiKey() {
+      return cloudinaryService.apiKey;
+    },
+    set apiKey(value: string | null) {
+      cloudinaryService.apiKey = value;
+    },
+    get apiSecret() {
+      return cloudinaryService.apiSecret;
+    },
+    set apiSecret(value: string | null) {
+      cloudinaryService.apiSecret = value;
+    },
+    get uploadPreset() {
+      return cloudinaryService.uploadPreset;
+    },
+    set uploadPreset(value: string | null) {
+      cloudinaryService.uploadPreset = value;
+    },
+    get dynamicFolders() {
+      return cloudinaryService.dynamicFolders;
+    },
+    set dynamicFolders(value: boolean) {
+      cloudinaryService.dynamicFolders = value;
+    },
+    get credentialsValid() {
+      return cloudinaryService.credentialsValid;
+    },
+    set credentialsValid(value: boolean | undefined) {
+      cloudinaryService.credentialsValid = value;
+    },
+    setCredentials(creds: Credentials) {
+      cloudinaryService.setCredentials(creds);
+      if (creds.cloudName && creds.apiKey && creds.apiSecret) {
+        updateCloudinaryConfig(creds.cloudName, creds.apiKey, creds.apiSecret);
+      }
+      void refreshEnvironmentViews();
+    },
+  };
 
-  // Set user platform for analytics
-  (cloudinary.utils as any).userPlatform = generateUserAgent();
+  // Check if this is the first run of the extension
+  const isFirstRun = context.globalState.get('cloudinary.firstRun', true);
 
-  cloudinary.config({
-    cloud_name: firstCloudName,
-    api_key: selectedEnv.apiKey,
-    api_secret: selectedEnv.apiSecret,
-  });
+  const openWelcomeOnFirstRun = async (): Promise<void> => {
+    if (!isFirstRun) {
+      return;
+    }
+    await context.globalState.update('cloudinary.firstRun', false);
+    await vscode.commands.executeCommand("cloudinary.openWelcomeScreen");
+  };
 
   statusBar = vscode.window.createStatusBarItem(
     vscode.StatusBarAlignment.Right,
     500
   );
-  // Status bar text will be updated after folder mode detection
-  statusBar.text = `$(cloud) ${cloudinaryProvider.cloudName}`;
-  statusBar.tooltip = "Click to switch Cloudinary environment";
-  statusBar.command = "cloudinary.switchEnvironment";
+  statusBar.text = `$(warning) Cloudinary: Not Configured`;
+  statusBar.tooltip = "Click to configure Cloudinary credentials";
+  statusBar.command = "cloudinary.openGlobalConfig";
   statusBar.show();
   context.subscriptions.push(statusBar);
 
-  // Reload config if file changes
-  const globalConfigPath = getGlobalConfigPath();
-  const watcher = vscode.workspace.createFileSystemWatcher(
-    new vscode.RelativePattern(
-      path.dirname(globalConfigPath),
-      path.basename(globalConfigPath)
-    )
+  const markNotConfigured = async (): Promise<void> => {
+    cloudinaryService.setCredentials({
+      cloudName: null,
+      apiKey: null,
+      apiSecret: null,
+      uploadPreset: null,
+      dynamicFolders: false,
+    });
+    cloudinaryService.credentialsValid = undefined;
+    statusBar.text = `$(warning) Cloudinary: Not Configured`;
+    statusBar.tooltip = "Click to configure Cloudinary credentials";
+    statusBar.command = "cloudinary.openGlobalConfig";
+    await refreshEnvironmentViews();
+  };
+
+  const applyEnvironment = async (
+    cloudName: string,
+    env: CloudinaryEnvironment,
+    entryPoint: string
+  ): Promise<void> => {
+    const { dynamicFolders, credentialsValid } = await resolveDynamicFolders(
+      cloudName,
+      env.apiKey,
+      env.apiSecret,
+      entryPoint
+    );
+    cloudinaryService.setCredentials({
+      cloudName,
+      apiKey: env.apiKey,
+      apiSecret: env.apiSecret,
+      uploadPreset: env.uploadPreset || null,
+      dynamicFolders,
+    });
+    cloudinaryService.credentialsValid = credentialsValid;
+    updateCloudinaryConfig(cloudName, env.apiKey, env.apiSecret);
+
+    statusBar.text = getStatusBarText(cloudName, dynamicFolders, credentialsValid);
+    statusBar.tooltip = getStatusBarTooltip(dynamicFolders, credentialsValid);
+    statusBar.command = "cloudinary.switchEnvironment";
+
+    await refreshEnvironmentViews();
+  };
+
+  registerAllCommands(
+    context,
+    cloudinaryService,
+    environmentTarget,
+    statusBar,
+    homescreenProvider,
+    libraryWebviewProvider,
+    docsAiProvider,
+    analytics
   );
 
-  watcher.onDidChange(async () => {
+  const refreshFromConfigFile = async (): Promise<void> => {
     const updatedEnvs = await loadEnvironments();
     const cloudNames = Object.keys(updatedEnvs);
 
     if (cloudNames.length === 0) {
-      vscode.window.showErrorMessage("❌ No Cloudinary environments found in updated config.");
+      await markNotConfigured();
       return;
     }
 
     // Try to keep the previously active cloud name
-    const preferredCloud = cloudinaryProvider.cloudName;
-    const newCloudName = cloudNames.includes(preferredCloud || '')
+    const preferredCloud = cloudinaryService.cloudName;
+    const newCloudName = preferredCloud && cloudNames.includes(preferredCloud)
       ? preferredCloud
       : cloudNames[0];
 
-    const env = updatedEnvs[newCloudName!];
+    const env = updatedEnvs[newCloudName];
 
-    // Check if updated credentials are still placeholders
-    if (isPlaceholderConfig(newCloudName!, env.apiKey, env.apiSecret)) {
-      statusBar.text = `$(warning) Cloudinary: Not Configured`;
-      statusBar.tooltip = "Click to configure Cloudinary credentials";
-      statusBar.command = "cloudinary.openGlobalConfig";
-      // Don't show message - just update status bar silently
+    if (
+      !hasCompleteEnvironment(newCloudName, env) ||
+      isPlaceholderConfig(newCloudName, env.apiKey, env.apiSecret)
+    ) {
+      await markNotConfigured();
       return;
     }
 
-    cloudinaryProvider.cloudName = newCloudName;
-    cloudinaryProvider.apiKey = env.apiKey;
-    cloudinaryProvider.apiSecret = env.apiSecret;
-    cloudinaryProvider.uploadPreset = env.uploadPreset || null;
-
-    // Update user platform for analytics
-    (cloudinary.utils as any).userPlatform = generateUserAgent();
-
-    cloudinary.config({
-      cloud_name: newCloudName!,
-      api_key: env.apiKey,
-      api_secret: env.apiSecret,
-    });
-
-    const cacheKey = `cloudinary.dynamicFolders.${newCloudName}`;
-    const cachedFolderMode = context.globalState.get(cacheKey) as boolean | undefined;
+    // The credentials file just changed; the keys (or the account's folder mode)
+    // may differ from what we cached, so force a fresh detection. This also
+    // re-validates the credentials so the status reflects whether they work.
+    await applyEnvironment(newCloudName, env, "config_change");
+  };
 
-    if (typeof cachedFolderMode === "boolean") {
-      cloudinaryProvider.dynamicFolders = cachedFolderMode;
-    } else {
-      cloudinaryProvider.dynamicFolders = await detectFolderMode(
-        newCloudName!,
-        env.apiKey,
-        env.apiSecret
-      );
-      context.globalState.update(cacheKey, cloudinaryProvider.dynamicFolders);
+  let configReloadTimer: ReturnType<typeof setTimeout> | undefined;
+  const scheduleConfigReload = (): void => {
+    if (configReloadTimer) {
+      clearTimeout(configReloadTimer);
     }
+    configReloadTimer = setTimeout(() => {
+      configReloadTimer = undefined;
+      void refreshFromConfigFile();
+    }, 250);
+  };
+  context.subscriptions.push({
+    dispose: () => {
+      if (configReloadTimer) {
+        clearTimeout(configReloadTimer);
+        configReloadTimer = undefined;
+      }
+    },
+  });
 
-    // Update status bar with folder mode indicator
-    statusBar.text = getStatusBarText(newCloudName!, cloudinaryProvider.dynamicFolders);
-    statusBar.tooltip = getStatusBarTooltip(cloudinaryProvider.dynamicFolders);
-    statusBar.command = "cloudinary.switchEnvironment";
-
-    cloudinaryProvider.refresh({
-      folderPath: '',
-      nextCursor: null,
-      searchQuery: null,
-      resourceTypeFilter: 'all'
-    });
+  // Reload config if the global file changes. VS Code's watcher can report
+  // editor saves as create/delete events, so all event types feed the same
+  // debounced refresh.
+  const globalConfigPath = getGlobalConfigPath();
+  const globalConfigDir = path.dirname(globalConfigPath);
+  const globalConfigFileName = path.basename(globalConfigPath);
+  const watcher = vscode.workspace.createFileSystemWatcher(
+    new vscode.RelativePattern(
+      globalConfigDir,
+      globalConfigFileName
+    )
+  );
 
-    cloudinaryProvider.notifyEnvironmentChange();
-  });
+  watcher.onDidChange(scheduleConfigReload);
+  watcher.onDidCreate(scheduleConfigReload);
+  watcher.onDidDelete(scheduleConfigReload);
 
   context.subscriptions.push(watcher);
 
-  // Detect and cache folder mode
-  const cacheKey = `cloudinary.dynamicFolders.${cloudinaryProvider.cloudName}`;
-  const cachedFolderMode = context.globalState.get(cacheKey) as boolean | undefined;
-
-  if (typeof cachedFolderMode === "boolean") {
-    cloudinaryProvider.dynamicFolders = cachedFolderMode;
-  } else {
-    cloudinaryProvider.dynamicFolders = await detectFolderMode(
-      cloudinaryProvider.cloudName,
-      cloudinaryProvider.apiKey,
-      cloudinaryProvider.apiSecret
-    );
-    context.globalState.update(cacheKey, cloudinaryProvider.dynamicFolders);
+  try {
+    const nodeWatcher = fs.watch(globalConfigDir, (_eventType, fileName) => {
+      if (fileName && fileName.toString() === globalConfigFileName) {
+        scheduleConfigReload();
+      }
+    });
+    context.subscriptions.push({ dispose: () => nodeWatcher.close() });
+  } catch {
+    // The VS Code watcher above is the primary path; this is only a fallback.
   }
 
-  // Update status bar with folder mode indicator
-  statusBar.text = getStatusBarText(cloudinaryProvider.cloudName, cloudinaryProvider.dynamicFolders);
-  statusBar.tooltip = getStatusBarTooltip(cloudinaryProvider.dynamicFolders);
-
-  vscode.window.registerTreeDataProvider(
-    "cloudinaryMediaLibrary",
-    cloudinaryProvider
+  // Manual escape hatch: force a fresh folder-mode detection. Useful after an
+  // account is migrated between fixed and dynamic folders, or to recover an
+  // install that cached the wrong mode.
+  context.subscriptions.push(
+    vscode.commands.registerCommand("cloudinary.refreshFolderMode", async () => {
+      const { cloudName, apiKey, apiSecret } = cloudinaryService;
+      if (!cloudName || !apiKey || !apiSecret || isPlaceholderConfig(cloudName, apiKey, apiSecret)) {
+        vscode.window.showWarningMessage(
+          "Configure Cloudinary credentials before refreshing the folder mode."
+        );
+        return;
+      }
+
+      const result = await detectFolderModeResult(cloudName, apiKey, apiSecret);
+      trackConfigValidation(analytics, result, "manual_refresh");
+
+      if (result.outcome !== "success") {
+        // Reflect rejected credentials in the status; leave a transient (e.g.
+        // network) failure as-is so we don't falsely mark working creds invalid.
+        if (result.errorReason === "unauthorized") {
+          cloudinaryService.credentialsValid = false;
+          statusBar.text = getStatusBarText(cloudName, cloudinaryService.dynamicFolders, false);
+          statusBar.tooltip = getStatusBarTooltip(cloudinaryService.dynamicFolders, false);
+          await refreshEnvironmentViews();
+        }
+        vscode.window.showWarningMessage(
+          "Could not refresh the Cloudinary folder mode. Check your credentials or connection, then try again."
+        );
+        return;
+      }
+
+      const dynamicFolders = result.dynamicFolders;
+      await writeFolderModeCache(context.globalState, cloudName, dynamicFolders);
+      cloudinaryService.dynamicFolders = dynamicFolders;
+      cloudinaryService.credentialsValid = true;
+
+      statusBar.text = getStatusBarText(cloudName, dynamicFolders, true);
+      statusBar.tooltip = getStatusBarTooltip(dynamicFolders, true);
+
+      await refreshEnvironmentViews();
+      vscode.window.showInformationMessage(
+        `Cloudinary folder mode: ${dynamicFolders ? "Dynamic" : "Fixed"} folders.`
+      );
+    })
   );
-  registerAllCommands(context, cloudinaryProvider, statusBar, homescreenProvider);
+
+  const environments = await loadEnvironments();
+  const firstCloudName = Object.keys(environments)[0];
+  const selectedEnv = environments[firstCloudName];
+
+  if (
+    !hasCompleteEnvironment(firstCloudName, selectedEnv) ||
+    isPlaceholderConfig(firstCloudName, selectedEnv.apiKey, selectedEnv.apiSecret)
+  ) {
+    await markNotConfigured();
+    await openWelcomeOnFirstRun();
+    return;
+  }
+
+  await applyEnvironment(firstCloudName, selectedEnv, "activation");
+  await openWelcomeOnFirstRun();
 }
 
 /**
diff --git a/src/test/suite/aiToolsGuidance.test.ts b/src/test/suite/aiToolsGuidance.test.ts
new file mode 100644
index 0000000..587ef3d
--- /dev/null
+++ b/src/test/suite/aiToolsGuidance.test.ts
@@ -0,0 +1,41 @@
+import * as assert from "assert";
+import { buildAiToolsNextStepsMessage } from "../../utils/aiToolsGuidance";
+
+suite("buildAiToolsNextStepsMessage", () => {
+  test("nothing installed → null (no message)", () => {
+    assert.strictEqual(buildAiToolsNextStepsMessage(0, 0), null);
+  });
+
+  test("skills only → no reload guidance", () => {
+    assert.strictEqual(
+      buildAiToolsNextStepsMessage(2, 0),
+      "Cloudinary: installed 2 skills."
+    );
+  });
+
+  test("single skill is singular", () => {
+    assert.strictEqual(
+      buildAiToolsNextStepsMessage(1, 0),
+      "Cloudinary: installed 1 skill."
+    );
+  });
+
+  test("MCP install includes reload/verify guidance with editor name", () => {
+    const msg = buildAiToolsNextStepsMessage(0, 1, "Claude Code");
+    assert.ok(msg);
+    assert.ok(msg!.startsWith("Cloudinary: installed 1 MCP server."));
+    assert.ok(msg!.includes("Reload Claude Code"));
+    assert.ok(msg!.includes("configured but inactive"));
+  });
+
+  test("skills + MCP combine, plural MCP", () => {
+    const msg = buildAiToolsNextStepsMessage(3, 2, "Cursor");
+    assert.ok(msg!.startsWith("Cloudinary: installed 3 skills and 2 MCP servers."));
+    assert.ok(msg!.includes("MCP servers connect"));
+  });
+
+  test("falls back to 'your editor' when label missing", () => {
+    const msg = buildAiToolsNextStepsMessage(0, 1);
+    assert.ok(msg!.includes("Reload your editor"));
+  });
+});
diff --git a/src/test/suite/analyticsService.test.ts b/src/test/suite/analyticsService.test.ts
new file mode 100644
index 0000000..9228054
--- /dev/null
+++ b/src/test/suite/analyticsService.test.ts
@@ -0,0 +1,150 @@
+import * as assert from "assert";
+import { AnalyticsService } from "../../analytics/analyticsService";
+
+class FakeStorage {
+  private values = new Map<string, unknown>();
+
+  get<T>(key: string, defaultValue: T): T {
+    return this.values.has(key) ? this.values.get(key) as T : defaultValue;
+  }
+
+  async update(key: string, value: unknown): Promise<void> {
+    this.values.set(key, value);
+  }
+}
+
+suite("AnalyticsService", () => {
+  test("sends analytics events with common context", async () => {
+    const urls: string[] = [];
+    const methods: string[] = [];
+    const service = new AnalyticsService({
+      extensionVersion: "1.2.3",
+      storage: new FakeStorage(),
+      getCloudName: () => "demo",
+      getDebugId: () => "debug-1",
+      getIdePlatform: () => "vscode",
+      createSessionId: () => "session-1",
+      now: () => new Date("2026-03-09T14:27:36.000Z"),
+      fetchFn: async (url, init) => {
+        urls.push(url);
+        methods.push(init.method);
+      },
+    });
+
+    await service.send("library_opened", { resource_type: "image", count: 2 });
+
+    assert.strictEqual(urls.length, 1);
+    assert.deepStrictEqual(methods, ["POST"]);
+    const url = new URL(urls[0]);
+    assert.strictEqual(url.origin, "https://analytics-api.cloudinary.com");
+    assert.strictEqual(url.pathname, "/vscode_extension");
+    assert.strictEqual(url.searchParams.get("source"), "vscode_extension");
+    assert.strictEqual(url.searchParams.get("event"), "library_opened");
+    assert.strictEqual(url.searchParams.get("extension_version"), "1.2.3");
+    assert.strictEqual(url.searchParams.get("ide_platform"), "vscode");
+    assert.strictEqual(url.searchParams.get("cloud_name"), "demo");
+    assert.strictEqual(url.searchParams.get("debug_id"), "debug-1");
+    assert.strictEqual(url.searchParams.get("session_id"), "session-1");
+    assert.strictEqual(url.searchParams.get("event_time"), "2026-03-09T14:27:36.000Z");
+    assert.strictEqual(url.searchParams.get("resource_type"), "image");
+    assert.strictEqual(url.searchParams.get("count"), "2");
+  });
+
+  test("marks the cloud as not configured when none is selected", async () => {
+    const urls: string[] = [];
+    const service = new AnalyticsService({
+      extensionVersion: "1.2.3",
+      storage: new FakeStorage(),
+      getCloudName: () => null,
+      fetchFn: async (url) => {
+        urls.push(url);
+      },
+    });
+
+    await service.send("extension_activated");
+
+    const url = new URL(urls[0]);
+    assert.strictEqual(url.searchParams.get("cloud_name"), "(not configured)");
+  });
+
+  test("persists and reuses a session id", async () => {
+    const storage = new FakeStorage();
+    const urls: string[] = [];
+    let createCount = 0;
+    const service = new AnalyticsService({
+      extensionVersion: "1.2.3",
+      storage,
+      createSessionId: () => `session-${++createCount}`,
+      fetchFn: async (url) => {
+        urls.push(url);
+      },
+    });
+
+    await service.send("extension_activated");
+    await service.send("home_opened");
+
+    assert.strictEqual(createCount, 1);
+    assert.strictEqual(new URL(urls[0]).searchParams.get("session_id"), "session-1");
+    assert.strictEqual(new URL(urls[1]).searchParams.get("session_id"), "session-1");
+    assert.strictEqual(new URL(urls[0]).searchParams.get("event"), "extension_activated");
+    assert.strictEqual(new URL(urls[1]).searchParams.get("event"), "home_opened");
+  });
+
+  test("drops unsafe event names and sensitive payload fields", async () => {
+    const urls: string[] = [];
+    const service = new AnalyticsService({
+      extensionVersion: "1.2.3",
+      storage: new FakeStorage(),
+      fetchFn: async (url) => {
+        urls.push(url);
+      },
+    });
+
+    await service.send("bad/event", { action: "ignored" });
+    await service.send("copy_message", {
+      copy_type: "code",
+      Event: "do_not_override",
+      nested: { should: "drop" },
+      tags: ["drop"],
+      infinite: Infinity,
+      has_initial_prompt: true,
+      prompt: "do not send",
+      apiKey: "do not send",
+      "client.secret": "do not send",
+      api_secret: "do not send",
+      email: "do-not-send@example.com",
+      "user.email": "do-not-send@example.com",
+      accessToken: "do not send",
+    });
+
+    assert.strictEqual(urls.length, 1);
+    const url = new URL(urls[0]);
+    assert.strictEqual(url.pathname, "/vscode_extension");
+    assert.strictEqual(url.searchParams.get("event"), "copy_message");
+    assert.strictEqual(url.searchParams.get("copy_type"), "code");
+    assert.strictEqual(url.searchParams.get("has_initial_prompt"), "true");
+    assert.strictEqual(url.searchParams.has("Event"), false);
+    assert.strictEqual(url.searchParams.has("nested"), false);
+    assert.strictEqual(url.searchParams.has("tags"), false);
+    assert.strictEqual(url.searchParams.has("infinite"), false);
+    assert.strictEqual(url.searchParams.has("prompt"), false);
+    assert.strictEqual(url.searchParams.has("apiKey"), false);
+    assert.strictEqual(url.searchParams.has("client.secret"), false);
+    assert.strictEqual(url.searchParams.has("api_secret"), false);
+    assert.strictEqual(url.searchParams.has("email"), false);
+    assert.strictEqual(url.searchParams.has("user.email"), false);
+    assert.strictEqual(url.searchParams.has("accessToken"), false);
+  });
+
+  test("swallows delivery failures", async () => {
+    const service = new AnalyticsService({
+      extensionVersion: "1.2.3",
+      storage: new FakeStorage(),
+      fetchFn: async () => {
+        throw new Error("network down");
+      },
+    });
+
+    await assert.doesNotReject(() => service.send("extension_activated"));
+  });
+});
diff --git a/src/test/suite/cloudinaryErrorHandler.test.ts b/src/test/suite/cloudinaryErrorHandler.test.ts
new file mode 100644
index 0000000..536a40d
--- /dev/null
+++ b/src/test/suite/cloudinaryErrorHandler.test.ts
@@ -0,0 +1,26 @@
+import * as assert from "assert";
+import { isCredentialError } from "../../utils/cloudinaryErrorHandler";
+
+suite("isCredentialError", () => {
+  test("detects auth HTTP codes from SDK-shaped errors", () => {
+    assert.strictEqual(isCredentialError({ error: { http_code: 401 } }), true);
+    assert.strictEqual(isCredentialError({ error: { http_code: 403 } }), true);
+    assert.strictEqual(isCredentialError({ http_code: 401 }), true);
+    assert.strictEqual(isCredentialError({ response: { status: 403 } }), true);
+  });
+
+  test("detects credential-related messages", () => {
+    assert.strictEqual(isCredentialError(new Error("Invalid Signature abc")), true);
+    assert.strictEqual(isCredentialError({ message: "Unknown API key 123" }), true);
+    assert.strictEqual(isCredentialError({ error: { message: "disabled account" } }), true);
+  });
+
+  test("does not flag unrelated errors", () => {
+    assert.strictEqual(isCredentialError({ error: { http_code: 404 } }), false);
+    assert.strictEqual(isCredentialError({ error: { http_code: 420 } }), false);
+    assert.strictEqual(isCredentialError(new Error("Network timeout")), false);
+    assert.strictEqual(isCredentialError({ message: "Resource not found" }), false);
+    assert.strictEqual(isCredentialError(undefined), false);
+    assert.strictEqual(isCredentialError(null), false);
+  });
+});
diff --git a/src/test/suite/cloudinaryService.test.ts b/src/test/suite/cloudinaryService.test.ts
new file mode 100644
index 0000000..5ba4116
--- /dev/null
+++ b/src/test/suite/cloudinaryService.test.ts
@@ -0,0 +1,397 @@
+import * as assert from 'assert';
+import { CloudinaryService, CloudinarySdkAdapter } from '../../cloudinary/cloudinaryService';
+import { ClientAsset } from '../../cloudinary/types';
+
+function fakeAdapter(overrides: Partial<CloudinarySdkAdapter> = {}): CloudinarySdkAdapter {
+  return {
+    subFolders: async () => ({ folders: [] }),
+    search: async () => ({ resources: [], next_cursor: null }),
+    uploadPresets: async () => ({ presets: [] }),
+    urlFor: (publicId, opts) => {
+      const tx = Array.isArray(opts.transformation) ? (opts.transformation as any[]) : [];
+      const flat = Object.assign({}, ...tx);
+      const parts: string[] = [];
+      if (flat.width) { parts.push(`w_${flat.width}`); }
+      if (flat.height) { parts.push(`h_${flat.height}`); }
+      if (flat.crop) { parts.push(`c_${flat.crop}`); }
+      if (flat.fetch_format) { parts.push(`f_${flat.fetch_format}`); }
+      if (flat.quality) { parts.push(`q_${flat.quality}`); }
+      const tail = parts.length ? `/${parts.join(',')}` : '';
+      const signature = opts.sign_url ? '/s--signed--' : '';
+      const format = opts.format ? `.${opts.format}` : '';
+      return `https://res.cloudinary.com/demo/${opts.resource_type}/${opts.type || 'upload'}${signature}${tail}/${publicId}${format}`;
+    },
+    ...overrides,
+  };
+}
+
+suite('CloudinaryService', () => {
+  test('constructs without credentials', () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    assert.strictEqual(svc.cloudName, null);
+    assert.strictEqual(svc.dynamicFolders, false);
+  });
+
+  test('setCredentials stores values', () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    assert.strictEqual(svc.cloudName, 'demo');
+    assert.strictEqual(svc.dynamicFolders, true);
+  });
+
+  test('setCredentials defaults uploadPreset to null when omitted', () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's' });
+    assert.strictEqual(svc.uploadPreset, null);
+    assert.strictEqual(svc.dynamicFolders, false);
+  });
+});
+
+suite('CloudinaryService.fetchChildren', () => {
+  test('returns folders and assets for root with dynamic folders', async () => {
+    const adapter = fakeAdapter({
+      subFolders: async (path) => {
+        assert.strictEqual(path, '');
+        return { folders: [{ name: 'photos', path: 'photos' }] };
+      },
+      search: async (opts) => {
+        assert.strictEqual(opts.expression, 'asset_folder=""');
+        return {
+          resources: [{
+            public_id: 'sample',
+            resource_type: 'image',
+            type: 'upload',
+            bytes: 1024,
+            secure_url: 'https://res.cloudinary.com/demo/image/upload/sample.jpg',
+          }],
+          next_cursor: null,
+        };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const page = await svc.fetchChildren('', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    assert.strictEqual(page.folders.length, 1);
+    assert.strictEqual(page.folders[0].name, 'photos');
+    assert.strictEqual(page.assets.length, 1);
+    assert.strictEqual(page.assets[0].public_id, 'sample');
+    assert.ok(page.assets[0].optimized_url.startsWith('https://'));
+    assert.ok(page.assets[0].optimized_url.includes('f_auto'), 'optimized_url should include f_auto');
+    assert.ok(page.assets[0].optimized_url.includes('q_auto'), 'optimized_url should include q_auto');
+    assert.ok(page.assets[0].thumbnail_url.includes('w_160'));
+    assert.strictEqual(page.nextCursor, null);
+  });
+
+  test('filters out nested assets at root in fixed folder mode', async () => {
+    const adapter = fakeAdapter({
+      subFolders: async () => ({ folders: [] }),
+      search: async () => ({
+        resources: [
+          { public_id: 'root', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          { public_id: 'foo/bar', resource_type: 'image', type: 'upload', secure_url: 'x' },
+        ],
+        next_cursor: null,
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: false });
+    const page = await svc.fetchChildren('', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    assert.strictEqual(page.assets.length, 1);
+    assert.strictEqual(page.assets[0].public_id, 'root');
+  });
+
+  test('respects resourceTypeFilter', async () => {
+    const adapter = fakeAdapter({
+      search: async () => ({
+        resources: [
+          { public_id: 'a', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          { public_id: 'b', resource_type: 'video', type: 'upload', secure_url: 'x' },
+        ],
+        next_cursor: null,
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const page = await svc.fetchChildren('', { resourceTypeFilter: 'image', sortDirection: 'desc' });
+    assert.strictEqual(page.assets.length, 1);
+    assert.strictEqual(page.assets[0].public_id, 'a');
+  });
+
+  test('raw asset: thumbnail_url equals optimized_url', async () => {
+    const adapter = fakeAdapter({
+      search: async () => ({
+        resources: [
+          { public_id: 'doc.pdf', resource_type: 'raw', type: 'upload', secure_url: 'x' },
+        ],
+        next_cursor: null,
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const page = await svc.fetchChildren('', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    assert.strictEqual(page.assets.length, 1);
+    assert.strictEqual(page.assets[0].thumbnail_url, page.assets[0].optimized_url);
+  });
+
+  test('authenticated asset uses signed original URL for preview fields', async () => {
+    const adapter = fakeAdapter({
+      search: async () => ({
+        resources: [
+          {
+            public_id: 'secure/sample',
+            resource_type: 'image',
+            type: 'authenticated',
+            format: 'jpg',
+            secure_url: 'https://res.cloudinary.com/demo/image/authenticated/secure/sample.jpg',
+          },
+        ],
+        next_cursor: null,
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const page = await svc.fetchChildren('', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    const asset = page.assets[0];
+
+    assert.strictEqual(asset.type, 'authenticated');
+    assert.ok(asset.secure_url.includes('/authenticated/s--signed--/'), 'secure_url should be signed');
+    assert.strictEqual(asset.optimized_url, asset.secure_url);
+    assert.strictEqual(asset.thumbnail_url, asset.secure_url);
+    assert.ok(!asset.secure_url.includes('f_auto'), 'authenticated original URL should not add dynamic transformations');
+    assert.ok(asset.secure_url.endsWith('/secure/sample.jpg'));
+  });
+
+  test('propagates nextCursor into the search call', async () => {
+    let seenCursor: string | undefined;
+    const adapter = fakeAdapter({
+      search: async (opts) => {
+        seenCursor = opts.nextCursor;
+        return { resources: [], next_cursor: null };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    await svc.fetchChildren('', { resourceTypeFilter: 'all', sortDirection: 'desc', nextCursor: 'abc123' });
+    assert.strictEqual(seenCursor, 'abc123');
+  });
+
+  test('fixed folder mode at non-root uses folder="path" expression', async () => {
+    let seenExpr: string | undefined;
+    const adapter = fakeAdapter({
+      subFolders: async () => ({ folders: [] }),
+      search: async (opts) => {
+        seenExpr = opts.expression;
+        return { resources: [], next_cursor: null };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: false });
+    await svc.fetchChildren('photos/2024', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    assert.strictEqual(seenExpr, 'folder="photos/2024"');
+  });
+});
+
+suite('CloudinaryService.prefetchRemaining', () => {
+  test('streams batches and stops when cursor is null', async () => {
+    let call = 0;
+    const adapter = fakeAdapter({
+      search: async () => {
+        call++;
+        if (call === 1) {
+          return { resources: [{ public_id: 'a', resource_type: 'image', type: 'upload', secure_url: 'x' }], next_cursor: 'c2' };
+        }
+        return { resources: [{ public_id: 'b', resource_type: 'image', type: 'upload', secure_url: 'x' }], next_cursor: null };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const batches: Array<{ assets: ClientAsset[]; hasMore: boolean }> = [];
+    await svc.prefetchRemaining('', 'c1', { resourceTypeFilter: 'all', sortDirection: 'desc' }, (assets, hasMore) => {
+      batches.push({ assets, hasMore });
+    });
+    assert.strictEqual(batches.length, 2);
+    assert.strictEqual(batches[0].hasMore, true);
+    assert.strictEqual(batches[1].hasMore, false);
+  });
+
+  test('cap-terminated stream reports hasMore=false on final batch', async () => {
+    const adapter = fakeAdapter({
+      search: async () => ({
+        resources: [
+          { public_id: 'a', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          { public_id: 'b', resource_type: 'image', type: 'upload', secure_url: 'x' },
+        ],
+        next_cursor: 'alive',
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const batches: Array<{ hasMore: boolean; count: number }> = [];
+    await svc.prefetchRemaining(
+      '',
+      'c1',
+      { resourceTypeFilter: 'all', sortDirection: 'desc' },
+      (assets, hasMore) => batches.push({ hasMore, count: assets.length }),
+      2, // cap
+    );
+    assert.strictEqual(batches.length, 1);
+    assert.strictEqual(batches[0].count, 2);
+    assert.strictEqual(batches[0].hasMore, false, 'cap-terminated stream must report hasMore=false');
+  });
+
+  test('continues after empty filtered batch', async () => {
+    let call = 0;
+    const adapter = fakeAdapter({
+      search: async () => {
+        call++;
+        if (call === 1) {
+          // All resources filtered out: fixed-folder root + nested public_ids.
+          return {
+            resources: [
+              { public_id: 'foo/a', resource_type: 'image', type: 'upload', secure_url: 'x' },
+              { public_id: 'foo/b', resource_type: 'image', type: 'upload', secure_url: 'x' },
+            ],
+            next_cursor: 'alive',
+          };
+        }
+        return {
+          resources: [
+            { public_id: 'root', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          ],
+          next_cursor: null,
+        };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: false });
+    const batches: Array<{ count: number; hasMore: boolean }> = [];
+    await svc.prefetchRemaining(
+      '',
+      'c1',
+      { resourceTypeFilter: 'all', sortDirection: 'desc' },
+      (assets, hasMore) => batches.push({ count: assets.length, hasMore }),
+    );
+    assert.strictEqual(call, 2);
+    assert.strictEqual(batches.length, 1);
+    assert.strictEqual(batches[0].count, 1);
+    assert.strictEqual(batches[0].hasMore, false);
+  });
+});
+
+suite('CloudinaryService.searchAssets', () => {
+  test('returns results and pages via prefetch', async () => {
+    let call = 0;
+    const adapter = fakeAdapter({
+      search: async (opts) => {
+        call++;
+        assert.ok(opts.expression.startsWith('foo'));
+        if (call === 1) {
+          return { resources: [{ public_id: 'foo1', resource_type: 'image', type: 'upload', secure_url: 'x' }], next_cursor: 'c2' };
+        }
+        return { resources: [{ public_id: 'foo2', resource_type: 'image', type: 'upload', secure_url: 'x' }], next_cursor: null };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const first = await svc.searchAssets('foo', { resourceTypeFilter: 'all', sortDirection: 'desc' });
+    assert.strictEqual(first.assets[0].public_id, 'foo1');
+    assert.strictEqual(first.nextCursor, 'c2');
+
+    const batches: ClientAsset[][] = [];
+    await svc.prefetchSearchResults('foo', 'c2', { resourceTypeFilter: 'all', sortDirection: 'desc' }, (a) => batches.push(a));
+    assert.strictEqual(batches.length, 1);
+    assert.strictEqual(batches[0][0].public_id, 'foo2');
+  });
+
+  test('applies resourceTypeFilter to search results', async () => {
+    const adapter = fakeAdapter({
+      search: async () => ({
+        resources: [
+          { public_id: 'image-1', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          { public_id: 'video-1', resource_type: 'video', type: 'upload', secure_url: 'x' },
+        ],
+        next_cursor: null,
+      }),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const result = await svc.searchAssets('foo', { resourceTypeFilter: 'image', sortDirection: 'desc' });
+    assert.strictEqual(result.assets.length, 1);
+    assert.strictEqual(result.assets[0].public_id, 'image-1');
+  });
+
+  test('prefetchSearchResults continues after empty filtered batch', async () => {
+    let call = 0;
+    const adapter = fakeAdapter({
+      search: async () => {
+        call++;
+        if (call === 1) {
+          return {
+            resources: [
+              { public_id: 'video-1', resource_type: 'video', type: 'upload', secure_url: 'x' },
+            ],
+            next_cursor: 'c2',
+          };
+        }
+
+        return {
+          resources: [
+            { public_id: 'image-1', resource_type: 'image', type: 'upload', secure_url: 'x' },
+          ],
+          next_cursor: null,
+        };
+      },
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', dynamicFolders: true });
+    const batches: ClientAsset[][] = [];
+
+    await svc.prefetchSearchResults(
+      'foo',
+      'c1',
+      { resourceTypeFilter: 'image', sortDirection: 'desc' },
+      (assets) => batches.push(assets),
+    );
+
+    assert.strictEqual(call, 2);
+    assert.strictEqual(batches.length, 1);
+    assert.strictEqual(batches[0][0].public_id, 'image-1');
+  });
+});
+
+suite('CloudinaryService.uploadPresets', () => {
+  test('fetchUploadPresets stores result', async () => {
+    const adapter = fakeAdapter({
+      uploadPresets: async () => ({ presets: [
+        { name: 'preset1', unsigned: true, settings: { folder: 'x' } },
+        { name: 'preset2', unsigned: false },
+      ]}),
+    });
+    const svc = new CloudinaryService(adapter);
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's' });
+    const presets = await svc.fetchUploadPresets();
+    assert.strictEqual(presets.length, 2);
+    assert.strictEqual(presets[0].signed, false);
+    assert.strictEqual(presets[1].signed, true);
+    assert.strictEqual(svc.uploadPresets.length, 2);
+  });
+
+  test('getCurrentUploadPreset returns configured preset when it exists', async () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', uploadPreset: 'p1' });
+    svc.uploadPresets = [{ name: 'p1', signed: true }];
+    assert.strictEqual(svc.getCurrentUploadPreset(), 'p1');
+  });
+
+  test('getCurrentUploadPreset returns null when configured preset missing', async () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    svc.setCredentials({ cloudName: 'demo', apiKey: 'k', apiSecret: 's', uploadPreset: 'ghost' });
+    svc.uploadPresets = [{ name: 'p1', signed: true }];
+    assert.strictEqual(svc.getCurrentUploadPreset(), null);
+  });
+
+  test('fetchUploadPresets throws when credentials missing', async () => {
+    const svc = new CloudinaryService(fakeAdapter());
+    await assert.rejects(svc.fetchUploadPresets(), /credentials/i);
+  });
+});
diff --git a/src/test/suite/configUtils.test.ts b/src/test/suite/configUtils.test.ts
new file mode 100644
index 0000000..19b86f4
--- /dev/null
+++ b/src/test/suite/configUtils.test.ts
@@ -0,0 +1,23 @@
+import * as assert from "assert";
+import { hasCompleteEnvironment } from "../../config/configUtils";
+
+suite("configUtils", () => {
+  suite("hasCompleteEnvironment", () => {
+    test("accepts a cloud keyed environment with required credentials", () => {
+      assert.strictEqual(
+        hasCompleteEnvironment("demo", { apiKey: "key", apiSecret: "secret" }),
+        true
+      );
+    });
+
+    test("rejects an empty config object", () => {
+      assert.strictEqual(hasCompleteEnvironment(undefined, undefined), false);
+    });
+
+    test("rejects an environment missing required credentials", () => {
+      assert.strictEqual(hasCompleteEnvironment("demo", {}), false);
+      assert.strictEqual(hasCompleteEnvironment("demo", { apiKey: "key" }), false);
+      assert.strictEqual(hasCompleteEnvironment("demo", { apiSecret: "secret" }), false);
+    });
+  });
+});
diff --git a/src/test/suite/connectionStatus.test.ts b/src/test/suite/connectionStatus.test.ts
new file mode 100644
index 0000000..d9adb46
--- /dev/null
+++ b/src/test/suite/connectionStatus.test.ts
@@ -0,0 +1,39 @@
+import * as assert from "assert";
+import { getConnectionStatus } from "../../config/connectionStatus";
+
+const base = { cloudName: "demo", apiKey: "key", apiSecret: "secret" };
+
+suite("getConnectionStatus", () => {
+  test("present + validated → connected", () => {
+    assert.strictEqual(getConnectionStatus({ ...base, credentialsValid: true }), "connected");
+  });
+
+  test("present + rejected → invalidCredentials (never 'connected' for bad creds)", () => {
+    assert.strictEqual(getConnectionStatus({ ...base, credentialsValid: false }), "invalidCredentials");
+  });
+
+  test("present + unknown (pending/offline) → checking (not connected, not broken)", () => {
+    assert.strictEqual(getConnectionStatus({ ...base, credentialsValid: undefined }), "checking");
+  });
+
+  test("missing any field → setupNeeded regardless of validity", () => {
+    assert.strictEqual(
+      getConnectionStatus({ cloudName: null, apiKey: "k", apiSecret: "s", credentialsValid: true }),
+      "setupNeeded"
+    );
+    assert.strictEqual(
+      getConnectionStatus({ cloudName: "c", apiKey: null, apiSecret: "s", credentialsValid: true }),
+      "setupNeeded"
+    );
+    assert.strictEqual(
+      getConnectionStatus({ cloudName: "c", apiKey: "k", apiSecret: null, credentialsValid: undefined }),
+      "setupNeeded"
+    );
+  });
+
+  test("the cached-invalid-credentials repro: a stale cache cannot make rejected creds 'connected'", () => {
+    // Simulates DOC-11110 repro: folder mode was cached (so dynamicFolders is
+    // known) but the current secret is now rejected → credentialsValid=false.
+    assert.strictEqual(getConnectionStatus({ ...base, credentialsValid: false }), "invalidCredentials");
+  });
+});
diff --git a/src/test/suite/detectFolderMode.test.ts b/src/test/suite/detectFolderMode.test.ts
new file mode 100644
index 0000000..0058054
--- /dev/null
+++ b/src/test/suite/detectFolderMode.test.ts
@@ -0,0 +1,125 @@
+import * as assert from "assert";
+import { detectFolderModeResult, resolveFolderModeState } from "../../config/detectFolderMode";
+
+suite("resolveFolderModeState", () => {
+  test("success marks credentials valid and uses detected folder mode", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState({ outcome: "success", dynamicFolders: true, status: 200 }),
+      { dynamicFolders: true, credentialsValid: true }
+    );
+  });
+
+  test("unauthorized credentials stay invalid even with a cached folder mode", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState(
+        {
+          outcome: "error",
+          errorReason: "unauthorized",
+          status: 401,
+          dynamicFolders: false,
+        },
+        { value: true, detectedAt: Date.now() }
+      ),
+      { dynamicFolders: false, credentialsValid: false }
+    );
+  });
+
+  test("transient failures can reuse cached folder mode without validating credentials", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState(
+        {
+          outcome: "error",
+          errorReason: "network_error",
+          dynamicFolders: false,
+        },
+        { value: true, detectedAt: Date.now() }
+      ),
+      { dynamicFolders: true, credentialsValid: undefined }
+    );
+  });
+
+  test("success (fixed mode) marks credentials valid", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState({ outcome: "success", dynamicFolders: false, status: 200 }),
+      { dynamicFolders: false, credentialsValid: true }
+    );
+  });
+
+  test("transient failure without a cache → unknown validity, default mode", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState({ outcome: "error", errorReason: "network_error", dynamicFolders: false }),
+      { dynamicFolders: false, credentialsValid: undefined }
+    );
+  });
+
+  test("skipped (placeholder/missing creds) → unknown validity", () => {
+    assert.deepStrictEqual(
+      resolveFolderModeState({ outcome: "skipped", errorReason: "placeholder", dynamicFolders: false }),
+      { dynamicFolders: false, credentialsValid: undefined }
+    );
+  });
+});
+
+suite("detectFolderModeResult", () => {
+  const originalFetch = globalThis.fetch;
+
+  teardown(() => {
+    (globalThis as any).fetch = originalFetch;
+  });
+
+  function mockConfigResponse(status: number, body: unknown): void {
+    (globalThis as any).fetch = async (url: string) => {
+      assert.strictEqual(url, "https://api.cloudinary.com/v1_1/demo/config?settings=true");
+      return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+      });
+    };
+  }
+
+  test("uses Admin API config folder_mode=dynamic", async () => {
+    mockConfigResponse(200, { settings: { folder_mode: "dynamic" } });
+
+    assert.deepStrictEqual(
+      await detectFolderModeResult("demo", "key", "secret"),
+      { dynamicFolders: true, outcome: "success", status: 200 }
+    );
+  });
+
+  test("uses Admin API config folder_mode=fixed", async () => {
+    mockConfigResponse(200, { settings: { folder_mode: "fixed" } });
+
+    assert.deepStrictEqual(
+      await detectFolderModeResult("demo", "key", "secret"),
+      { dynamicFolders: false, outcome: "success", status: 200 }
+    );
+  });
+
+  test("does not infer dynamic mode from any successful config response", async () => {
+    mockConfigResponse(200, { settings: {} });
+
+    assert.deepStrictEqual(
+      await detectFolderModeResult("demo", "key", "secret"),
+      {
+        dynamicFolders: false,
+        outcome: "error",
+        status: 200,
+        errorReason: "unexpected_response",
+      }
+    );
+  });
+
+  test("marks rejected credentials unauthorized", async () => {
+    mockConfigResponse(401, { error: { message: "Unauthorized" } });
+
+    assert.deepStrictEqual(
+      await detectFolderModeResult("demo", "key", "secret"),
+      {
+        dynamicFolders: false,
+        outcome: "error",
+        status: 401,
+        errorReason: "unauthorized",
+      }
+    );
+  });
+});
diff --git a/src/test/suite/folderModeCache.test.ts b/src/test/suite/folderModeCache.test.ts
new file mode 100644
index 0000000..50461b0
--- /dev/null
+++ b/src/test/suite/folderModeCache.test.ts
@@ -0,0 +1,80 @@
+import * as assert from "assert";
+import * as vscode from "vscode";
+import {
+  folderModeCacheKey,
+  readFolderModeCache,
+  writeFolderModeCache,
+} from "../../config/folderModeCache";
+
+/** Minimal in-memory Memento for testing. */
+class FakeStorage implements Pick<vscode.Memento, "get" | "update"> {
+  private values = new Map<string, unknown>();
+
+  constructor(seed: Record<string, unknown> = {}) {
+    for (const [k, v] of Object.entries(seed)) {
+      this.values.set(k, v);
+    }
+  }
+
+  get<T>(key: string, defaultValue?: T): T | undefined {
+    return this.values.has(key) ? (this.values.get(key) as T) : defaultValue;
+  }
+
+  async update(key: string, value: unknown): Promise<void> {
+    this.values.set(key, value);
+  }
+
+  raw(key: string): unknown {
+    return this.values.get(key);
+  }
+}
+
+const memento = (storage: FakeStorage) => storage as unknown as vscode.Memento;
+
+suite("folderModeCache", () => {
+  test("readFolderModeCache returns a timestamped entry", () => {
+    const entry = { value: true, detectedAt: 1000 };
+    const storage = new FakeStorage({ [folderModeCacheKey("demo")]: entry });
+    assert.deepStrictEqual(readFolderModeCache(memento(storage), "demo"), entry);
+  });
+
+  test("readFolderModeCache ignores legacy plain-boolean entries", () => {
+    const storage = new FakeStorage({ [folderModeCacheKey("demo")]: true });
+    assert.strictEqual(readFolderModeCache(memento(storage), "demo"), undefined);
+  });
+
+  test("readFolderModeCache ignores malformed timestamped entries", () => {
+    const missingValue = new FakeStorage({
+      [folderModeCacheKey("demo")]: { detectedAt: 1000 },
+    });
+    const nonFiniteTimestamp = new FakeStorage({
+      [folderModeCacheKey("demo")]: { value: true, detectedAt: Number.NaN },
+    });
+
+    assert.strictEqual(readFolderModeCache(memento(missingValue), "demo"), undefined);
+    assert.strictEqual(readFolderModeCache(memento(nonFiniteTimestamp), "demo"), undefined);
+  });
+
+  test("readFolderModeCache returns undefined when absent", () => {
+    assert.strictEqual(readFolderModeCache(memento(new FakeStorage()), "demo"), undefined);
+  });
+
+  test("writeFolderModeCache persists a timestamped entry", async () => {
+    const storage = new FakeStorage();
+    await writeFolderModeCache(memento(storage), "demo", true, 4242);
+    assert.deepStrictEqual(storage.raw(folderModeCacheKey("demo")), {
+      value: true,
+      detectedAt: 4242,
+    });
+  });
+
+  test("write then read round-trips", async () => {
+    const storage = new FakeStorage();
+    const now = 50_000;
+    await writeFolderModeCache(memento(storage), "demo", false, now);
+    const cached = readFolderModeCache(memento(storage), "demo");
+    assert.ok(cached);
+    assert.strictEqual(cached!.value, false);
+    assert.strictEqual(cached!.detectedAt, now);
+  });
+});
diff --git a/src/test/suite/libraryRowSplice.test.ts b/src/test/suite/libraryRowSplice.test.ts
new file mode 100644
index 0000000..5ae4564
--- /dev/null
+++ b/src/test/suite/libraryRowSplice.test.ts
@@ -0,0 +1,18 @@
+import * as assert from 'assert';
+import { spliceOutRangeAtDepth } from '../../webview/client/libraryRowSplice';
+
+suite('spliceOutRangeAtDepth', () => {
+  test('removes contiguous rows at target depth (exclusive boundary)', () => {
+    const rows = [
+      { depth: 0 },
+      { depth: 1 },
+      { depth: 1 },
+      { depth: 2 },
+      { depth: 1 },
+      { depth: 0 },
+    ];
+
+    const end = spliceOutRangeAtDepth(rows, 1, 1);
+    assert.strictEqual(end, 5);
+  });
+});
diff --git a/src/test/suite/libraryVirtualList.test.ts b/src/test/suite/libraryVirtualList.test.ts
new file mode 100644
index 0000000..3c4710e
--- /dev/null
+++ b/src/test/suite/libraryVirtualList.test.ts
@@ -0,0 +1,30 @@
+import * as assert from 'assert';
+import { computeWindow } from '../../webview/client/libraryVirtualList';
+
+suite('libraryVirtualList.computeWindow', () => {
+  test('returns viewport range with buffer', () => {
+    const windowRange = computeWindow({
+      scrollTop: 100,
+      viewportHeight: 220,
+      rowHeight: 22,
+      totalRows: 1000,
+      buffer: 5,
+    });
+
+    assert.strictEqual(windowRange.startIdx, 0);
+    assert.strictEqual(windowRange.endIdx, 19);
+    assert.ok(windowRange.startOffset % 22 === 0);
+  });
+
+  test('clamps endIdx to total rows', () => {
+    const windowRange = computeWindow({
+      scrollTop: 10000,
+      viewportHeight: 100,
+      rowHeight: 22,
+      totalRows: 50,
+      buffer: 5,
+    });
+
+    assert.strictEqual(windowRange.endIdx, 50);
+  });
+});
diff --git a/src/test/suite/uploadWidget.test.ts b/src/test/suite/uploadWidget.test.ts
new file mode 100644
index 0000000..364be54
--- /dev/null
+++ b/src/test/suite/uploadWidget.test.ts
@@ -0,0 +1,174 @@
+import * as assert from 'assert';
+import { uploadWidgetTestApi } from '../../commands/uploadWidget';
+import { buildUploadPresetOptions } from '../../webview/client/uploadPresetOptions';
+
+function uploadState(overrides: Record<string, unknown> = {}) {
+  return {
+    cloudName: 'demo',
+    apiKey: 'key',
+    apiSecret: 'secret',
+    uploadPresets: [],
+    dynamicFolders: true,
+    fetchUploadPresets: async () => [],
+    getCurrentUploadPreset: () => null,
+    listAllFolders: async () => [],
+    ...overrides,
+  } as any;
+}
+
+suite('Upload widget folder options', () => {
+  teardown(() => {
+    uploadWidgetTestApi.clearFolderOptionsCache();
+  });
+
+  test('caches successful folder loads for subsequent panel opens', async () => {
+    const folders = await uploadWidgetTestApi.collectFolderOptions(uploadState({
+      listAllFolders: async () => [
+        { path: 'docs', name: 'docs' },
+        { path: 'docs/sdk', name: 'sdk' },
+      ],
+    }));
+
+    assert.deepStrictEqual(
+      folders.map((folder) => folder.path),
+      ['', 'docs', 'docs/sdk']
+    );
+
+    const initialFolders = uploadWidgetTestApi.getInitialFolderOptions('demo');
+    assert.deepStrictEqual(
+      initialFolders.map((folder) => folder.path),
+      ['', 'docs', 'docs/sdk']
+    );
+  });
+
+  test('keeps cached folders instead of falling back to root after a later fetch failure', async () => {
+    await uploadWidgetTestApi.collectFolderOptions(uploadState({
+      listAllFolders: async () => [{ path: 'Marketing', name: 'Marketing' }],
+    }));
+
+    const folders = await uploadWidgetTestApi.collectFolderOptions(uploadState({
+      listAllFolders: async () => {
+        throw new Error('temporary timeout');
+      },
+    }));
+
+    assert.deepStrictEqual(
+      folders.map((folder) => folder.path),
+      ['', 'Marketing']
+    );
+  });
+
+  test('does not reuse one cloud folder cache for another cloud', async () => {
+    await uploadWidgetTestApi.collectFolderOptions(uploadState({
+      cloudName: 'cloudinary',
+      listAllFolders: async () => [{ path: 'docs', name: 'docs' }],
+    }));
+
+    const folders = await uploadWidgetTestApi.collectFolderOptions(uploadState({
+      cloudName: 'demo',
+      listAllFolders: async () => {
+        throw new Error('unauthorized');
+      },
+    }));
+
+    assert.deepStrictEqual(
+      folders.map((folder) => folder.path),
+      ['']
+    );
+  });
+});
+
+suite('Upload widget upload options', () => {
+  test('keeps no-preset option when fetched presets refresh the dropdown', () => {
+    assert.deepStrictEqual(
+      buildUploadPresetOptions([{ name: 'auto-chaptering', signed: true }]),
+      [
+        { value: '', label: 'No preset (signed upload)' },
+        { value: 'auto-chaptering', label: 'auto-chaptering (Signed)' },
+      ]
+    );
+  });
+
+  test('renders no-preset option before fetched presets', () => {
+    const html = uploadWidgetTestApi.getUploadContent(
+      '',
+      [{ name: 'auto-chaptering', signed: true }],
+      '',
+      [{ path: '', label: '/ (root)' }]
+    );
+
+    const noPresetIdx = html.indexOf('No preset (signed upload)');
+    const presetIdx = html.indexOf('auto-chaptering (Signed)');
+
+    assert.ok(noPresetIdx >= 0, 'expected upload dropdown to include no-preset option');
+    assert.ok(presetIdx >= 0, 'expected upload dropdown to include fetched preset');
+    assert.ok(noPresetIdx < presetIdx, 'expected no-preset option to appear first');
+  });
+
+  test('omits upload_preset when no preset is selected', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState(),
+      null,
+      '',
+    );
+
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'upload_preset'), false);
+  });
+
+  test('omits upload_preset for an empty preset value', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState(),
+      '',
+      '',
+    );
+
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'upload_preset'), false);
+  });
+
+  test('includes upload_preset when a preset is selected', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState(),
+      'cld-docs',
+      '',
+    );
+
+    assert.strictEqual(options.upload_preset, 'cld-docs');
+  });
+
+  test('uses folder for fixed-folder environments', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState({ dynamicFolders: false }),
+      null,
+      'docs/mediaflows',
+    );
+
+    assert.strictEqual(options.folder, 'docs/mediaflows');
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'asset_folder'), false);
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'use_asset_folder_as_public_id_prefix'), false);
+  });
+
+  test('uses asset_folder for dynamic-folder environments without changing the public ID path', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState({ dynamicFolders: true }),
+      null,
+      'docs/mediaflows',
+    );
+
+    assert.strictEqual(options.asset_folder, 'docs/mediaflows');
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'folder'), false);
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'use_asset_folder_as_public_id_prefix'), false);
+  });
+
+  test('preserves explicit public IDs in dynamic-folder environments', () => {
+    const options = uploadWidgetTestApi.getUploadOptions(
+      uploadState({ dynamicFolders: true }),
+      null,
+      'docs/mediaflows',
+      'docs/mediaflows/custom-id',
+    );
+
+    assert.strictEqual(options.asset_folder, 'docs/mediaflows');
+    assert.strictEqual(options.public_id, 'docs/mediaflows/custom-id');
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(options, 'use_asset_folder_as_public_id_prefix'), false);
+  });
+});
diff --git a/src/tree/cloudinaryItem.ts b/src/tree/cloudinaryItem.ts
deleted file mode 100644
index 5514da4..0000000
--- a/src/tree/cloudinaryItem.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-// === 📁 src/tree/cloudinaryItem.ts ===
-import * as vscode from 'vscode';
-import { v2 as cloudinary } from 'cloudinary';
-
-export type CloudinaryItemType = 'asset' | 'folder' | 'divider' | 'clearSearch' | 'loading';
-
-interface AssetData {
-  public_id: string;
-  display_name?: string;
-  resource_type: string;
-  type?: string;
-  [key: string]: any;
-}
-
-interface FolderData {
-  name?: string;
-  path?: string;
-  [key: string]: any;
-}
-
-export type ItemData = AssetData | FolderData | Record<string, unknown>;
-
-/**
- * Represents a single item in the Cloudinary Tree View.
- */
-class CloudinaryItem extends vscode.TreeItem {
-  public type: CloudinaryItemType;
-  public data: ItemData;
-
-  constructor(
-    label: string,
-    collapsibleState: vscode.TreeItemCollapsibleState,
-    type: CloudinaryItemType,
-    data: ItemData,
-    cloudName?: string,
-    dynamicFolders = false
-  ) {
-    const isAsset = type === 'asset';
-    const labelToDisplay =
-      isAsset && dynamicFolders && 'display_name' in data
-        ? data.display_name || (data.public_id?.split('/').pop() ?? label)
-        : label;
-
-    // Truncate the label if it's too long, but keep the full name in tooltip
-    const truncatedLabel = truncateLabel(labelToDisplay);
-    super(truncatedLabel, collapsibleState);
-    this.tooltip = labelToDisplay; // Show full name on hover
-
-    this.type = type;
-    this.data = data;
-
-    if (type === 'asset' && 'public_id' in data && 'resource_type' in data) {
-      const assetType = data.resource_type;
-
-      let optimizedUrl =
-        assetType === 'raw'
-          ? cloudinary.url(data.public_id, {
-            resource_type: 'raw',
-            type: data.type,
-          })
-          : cloudinary.url(data.public_id, {
-            resource_type: assetType,
-            type: data.type,
-            transformation: [
-              { fetch_format: assetType === 'video' ? 'auto:video' : 'auto' },
-              { quality: 'auto' }
-            ],
-          });
-
-      data.optimized_url = optimizedUrl;
-      data.displayType = assetType;
-
-      // Format file size and type for display
-      const fileSize = data.bytes ? formatFileSize(data.bytes) : '';
-      const fileType = data.format ? data.format.toUpperCase() : assetType.toUpperCase();
-      this.description = `${fileType} • ${fileSize}`;
-
-      this.contextValue = 'asset';
-      this.iconPath = new vscode.ThemeIcon(
-        assetType === 'video'
-          ? 'device-camera-video'
-          : assetType === 'raw'
-            ? 'file'
-            : 'file-media'
-      );
-
-      this.command = {
-        command: 'cloudinary.openAsset',
-        title: 'Open Asset',
-        arguments: [data],
-      };
-    }
-
-    // === FOLDER NODE ===
-    else if (type === 'folder') {
-      this.contextValue = 'folder';
-      this.iconPath = new vscode.ThemeIcon('folder');
-    }
-
-    // === DIVIDER NODE ===
-    else if (type === 'divider') {
-      this.contextValue = undefined;
-      this.iconPath = new vscode.ThemeIcon('ellipsis');
-      this.tooltip = 'Additional assets loaded';
-      this.description = true;
-    }
-    // === CLEAR SEARCH NODE ===
-    else if (type === 'clearSearch') {
-      this.contextValue = 'clearSearch';
-      this.iconPath = new vscode.ThemeIcon('close');
-      this.command = {
-        command: 'cloudinary.clearSearch',
-        title: 'Clear Search',
-      };
-    }
-    // === LOADING INDICATOR NODE ===
-    else if (type === 'loading') {
-      this.contextValue = undefined;
-      this.iconPath = new vscode.ThemeIcon('loading~spin');
-      this.tooltip = 'Loading additional assets in the background...';
-    }
-  }
-}
-
-function truncateLabel(label: string, maxLength: number = 20): string {
-  if (label.length <= maxLength) { return label; }
-  const extension = label.includes('.') ? label.split('.').pop() : '';
-  const nameWithoutExt = extension ? label.slice(0, -(extension.length + 1)) : label;
-  const truncatedName = nameWithoutExt.slice(0, maxLength - 3) + '...';
-  return extension ? `${truncatedName}.${extension}` : truncatedName;
-}
-
-function formatFileSize(bytes: number): string {
-  if (bytes === 0) { return '0 B'; }
-  const k = 1024;
-  const sizes = ['B', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
-}
-
-export default CloudinaryItem;
\ No newline at end of file
diff --git a/src/tree/treeDataProvider.ts b/src/tree/treeDataProvider.ts
deleted file mode 100644
index b7c6250..0000000
--- a/src/tree/treeDataProvider.ts
+++ /dev/null
@@ -1,593 +0,0 @@
-import * as vscode from 'vscode';
-import { v2 as cloudinary } from 'cloudinary';
-import CloudinaryItem from './cloudinaryItem';
-import { handleCloudinaryError } from '../utils/cloudinaryErrorHandler';
-import { isPlaceholderConfig } from '../config/configUtils';
-
-export class CloudinaryTreeDataProvider implements vscode.TreeDataProvider<CloudinaryItem> {
-  // Cloudinary credentials
-  apiKey: string | null = null;
-  apiSecret: string | null = null;
-  cloudName: string | null = null;
-  uploadPreset: string | null = null;
-  uploadPresets: Array<{
-    name: string;
-    signed: boolean;
-    settings?: {}
-  }> = [];
-
-  dynamicFolders = false;
-
-  private viewState = {
-    folderPath: '',
-    nextCursor: null as string | null,
-    searchQuery: null as string | null,
-    isPaginating: false,
-    resourceTypeFilter: 'all' as 'image' | 'video' | 'raw' | 'all',
-    sortDirection: 'desc' as 'asc' | 'desc',
-  };
-
-  private assetMap: Map<string, CloudinaryItem[]> = new Map();
-
-  // Track folders currently being prefetched to prevent duplicate requests
-  private prefetchingFolders: Set<string> = new Set();
-
-  // Maximum assets to load per folder (to prevent endless fetching for huge folders)
-  private readonly MAX_ASSETS_PER_FOLDER = 5000;
-
-  private _onDidChangeTreeData = new vscode.EventEmitter<CloudinaryItem | undefined | void>();
-  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;
-
-  private _onDidChangeEnvironment = new vscode.EventEmitter<void>();
-  readonly onDidChangeEnvironment = this._onDidChangeEnvironment.event;
-
-  /**
-   * Fires the onDidChangeEnvironment event to notify subscribers that
-   * credentials have changed to a new environment.
-   */
-  notifyEnvironmentChange(): void {
-    this._onDidChangeEnvironment.fire();
-  }
-
-  /**
-   * Refreshes the tree data view.
-   */
-  refresh(stateUpdate: Partial<typeof this.viewState> = {}, append = false) {
-    this.viewState = {
-      ...this.viewState,
-      ...stateUpdate,
-      isPaginating: !!stateUpdate.nextCursor,
-    };
-
-    if (!append && !this.viewState.isPaginating) {
-      this.assetMap.clear();
-    }
-
-    this._onDidChangeTreeData.fire();
-  }
-
-  getTreeItem(element: CloudinaryItem): vscode.TreeItem {
-    return element;
-  }
-
-  async getChildren(element?: CloudinaryItem): Promise<CloudinaryItem[]> {
-    if (!this.apiKey || !this.apiSecret || !this.cloudName) {
-      return [];
-    }
-
-    // Prevent API calls with placeholder credentials
-    if (isPlaceholderConfig(this.cloudName, this.apiKey, this.apiSecret)) {
-      return [];
-    }
-
-    if (!element) {
-      if (this.viewState.searchQuery) {
-        const results = await this.searchAssets(this.viewState.searchQuery);
-        const clear = new CloudinaryItem("Clear Search", vscode.TreeItemCollapsibleState.None, "clearSearch", {});
-        return [clear, ...results];
-      }
-      return this.assetMap.get('') || await this.fetchFoldersAndAssets('');
-    }
-
-    if (element.type === 'folder' && 'path' in element.data) {
-      const folderPath = element.data.path || '';
-      return this.assetMap.get(folderPath) || await this.fetchFoldersAndAssets(folderPath);
-    }
-
-    return [];
-  }
-
-  async fetchFoldersAndAssets(
-    folderPath = '',
-    nextCursor: string | null = null,
-    append = false
-  ): Promise<CloudinaryItem[]> {
-    try {
-      const maxResults = 500;
-
-      // Build expression based on folder mode
-      // Dynamic folders: use asset_folder field to prevent duplicates
-      // Fixed folders: use folder field (or empty for root to get all, then filter)
-      let expression: string;
-      if (this.dynamicFolders) {
-        // Dynamic folders: use asset_folder to only get assets in this specific folder
-        expression = folderPath ? `asset_folder="${folderPath}"` : 'asset_folder=""';
-      } else {
-        // Fixed folders: use folder field (empty returns all, filtered below)
-        expression = folderPath ? `folder="${folderPath}"` : '';
-      }
-
-      const folderPromise = cloudinary.api.sub_folders(folderPath);
-      const assetQuery = cloudinary.search
-        .expression(expression)
-        .sort_by('created_at', this.viewState.sortDirection)
-        .max_results(maxResults)
-        .with_field(["tags", "context", "metadata"]);
-
-      if (nextCursor) { assetQuery.next_cursor(nextCursor); }
-
-      const [foldersResult, assetsResult] = await Promise.all([
-        folderPromise,
-        assetQuery.execute(),
-      ]);
-
-      const folders = (foldersResult.folders || []).map(
-        (folder: any) =>
-          new CloudinaryItem(
-            folder.name,
-            vscode.TreeItemCollapsibleState.Collapsed,
-            'folder',
-            folder,
-            this.cloudName!,
-            this.dynamicFolders
-          )
-      );
-
-      const filteredAssets = assetsResult.resources.filter((asset: any) => {
-        // For fixed folders at root level, filter out nested assets (they'll appear in their folders)
-        if (!this.dynamicFolders && folderPath === '') {
-          const isNestedAsset = asset.public_id.includes('/');
-          if (isNestedAsset) { return false; }
-        }
-        // Apply resource type filter
-        if (this.viewState.resourceTypeFilter === 'all') { return true; }
-        return asset.resource_type?.toLowerCase() === this.viewState.resourceTypeFilter;
-      });
-
-      const newAssets = filteredAssets.map(
-        (asset: any) =>
-          new CloudinaryItem(
-            asset.public_id,
-            vscode.TreeItemCollapsibleState.None,
-            'asset',
-            asset,
-            this.cloudName!,
-            this.dynamicFolders
-          )
-      );
-
-      if (!append) {
-        this.assetMap.set(folderPath, [...folders, ...newAssets]);
-      } else {
-        const existing = this.assetMap.get(folderPath) || [];
-        this.assetMap.set(folderPath, [...existing, ...newAssets]);
-      }
-
-      // If there are more assets, start background pre-fetching
-      if (assetsResult.next_cursor && !append) {
-        this.viewState.nextCursor = assetsResult.next_cursor;
-
-        // Add a loading indicator while prefetching
-        const loadingItem = new CloudinaryItem(
-          'Loading more assets...',
-          vscode.TreeItemCollapsibleState.None,
-          'loading',
-          { folderPath }
-        );
-        const currentList = this.assetMap.get(folderPath) || [];
-        this.assetMap.set(folderPath, [...currentList, loadingItem]);
-
-        // Start background prefetch (don't await - let it run async)
-        this.prefetchRemainingAssets(folderPath, assetsResult.next_cursor);
-      } else if (assetsResult.next_cursor && append) {
-        // Continue prefetching if this was a prefetch call with more data
-        this.viewState.nextCursor = assetsResult.next_cursor;
-      } else {
-        this.viewState.nextCursor = null;
-      }
-
-      return this.assetMap.get(folderPath) || [];
-    } catch (err: any) {
-      handleCloudinaryError('Failed to fetch folders or assets', err);
-      return [];
-    }
-  }
-
-  /**
-   * Background pre-fetches remaining assets for a folder.
-   * Runs asynchronously and updates the tree as more assets are loaded.
-   */
-  private async prefetchRemainingAssets(folderPath: string, initialCursor: string): Promise<void> {
-    // Prevent duplicate prefetching for the same folder
-    if (this.prefetchingFolders.has(folderPath)) {
-      return;
-    }
-    this.prefetchingFolders.add(folderPath);
-
-    try {
-      let nextCursor: string | null = initialCursor;
-      let totalAssets = this.countAssetsInFolder(folderPath);
-
-      while (nextCursor && totalAssets < this.MAX_ASSETS_PER_FOLDER) {
-        const result = await this.fetchAssetsPage(folderPath, nextCursor);
-
-        if (result.assets.length === 0) {
-          break;
-        }
-
-        // Remove the loading indicator and append new assets
-        this.appendPrefetchedAssets(folderPath, result.assets, result.nextCursor);
-        totalAssets += result.assets.length;
-        nextCursor = result.nextCursor;
-
-        // Fire tree update to show new assets
-        this._onDidChangeTreeData.fire();
-      }
-
-      // Remove any remaining loading indicator
-      this.removeLoadingIndicator(folderPath);
-      this._onDidChangeTreeData.fire();
-    } catch (err: any) {
-      // Remove loading indicator on error
-      this.removeLoadingIndicator(folderPath);
-      this._onDidChangeTreeData.fire();
-      // Don't show error for background operations - they're non-critical
-      console.error('Background prefetch error:', err);
-    } finally {
-      this.prefetchingFolders.delete(folderPath);
-    }
-  }
-
-  /**
-   * Fetches a single page of assets for prefetching.
-   */
-  private async fetchAssetsPage(
-    folderPath: string,
-    cursor: string
-  ): Promise<{ assets: CloudinaryItem[]; nextCursor: string | null }> {
-    const maxResults = 500;
-
-    let expression: string;
-    if (this.dynamicFolders) {
-      expression = folderPath ? `asset_folder="${folderPath}"` : 'asset_folder=""';
-    } else {
-      expression = folderPath ? `folder="${folderPath}"` : '';
-    }
-
-    const assetQuery = cloudinary.search
-      .expression(expression)
-      .sort_by('created_at', this.viewState.sortDirection)
-      .max_results(maxResults)
-      .with_field(["tags", "context", "metadata"])
-      .next_cursor(cursor);
-
-    const assetsResult = await assetQuery.execute();
-
-    const filteredAssets = assetsResult.resources.filter((asset: any) => {
-      if (!this.dynamicFolders && folderPath === '') {
-        const isNestedAsset = asset.public_id.includes('/');
-        if (isNestedAsset) { return false; }
-      }
-      if (this.viewState.resourceTypeFilter === 'all') { return true; }
-      return asset.resource_type?.toLowerCase() === this.viewState.resourceTypeFilter;
-    });
-
-    const assets = filteredAssets.map(
-      (asset: any) =>
-        new CloudinaryItem(
-          asset.public_id,
-          vscode.TreeItemCollapsibleState.None,
-          'asset',
-          asset,
-          this.cloudName!,
-          this.dynamicFolders
-        )
-    );
-
-    return {
-      assets,
-      nextCursor: assetsResult.next_cursor || null,
-    };
-  }
-
-  /**
-   * Appends prefetched assets to the folder's cache.
-   */
-  private appendPrefetchedAssets(
-    folderPath: string,
-    newAssets: CloudinaryItem[],
-    hasMore: string | null
-  ): void {
-    const items = this.assetMap.get(folderPath) || [];
-
-    // Remove the loading indicator if present
-    const filteredItems = items.filter(item => item.type !== 'loading');
-
-    // Append new assets
-    const updatedItems = [...filteredItems, ...newAssets];
-
-    // Add loading indicator back if there's more to fetch
-    if (hasMore) {
-      updatedItems.push(
-        new CloudinaryItem(
-          'Loading more assets...',
-          vscode.TreeItemCollapsibleState.None,
-          'loading',
-          { folderPath }
-        )
-      );
-    }
-
-    this.assetMap.set(folderPath, updatedItems);
-  }
-
-  /**
-   * Removes the loading indicator from a folder.
-   */
-  private removeLoadingIndicator(folderPath: string): void {
-    const items = this.assetMap.get(folderPath);
-    if (!items) { return; }
-
-    const filteredItems = items.filter(item => item.type !== 'loading');
-    this.assetMap.set(folderPath, filteredItems);
-  }
-
-  /**
-   * Counts the number of assets currently loaded for a folder.
-   */
-  private countAssetsInFolder(folderPath: string): number {
-    const items = this.assetMap.get(folderPath) || [];
-    return items.filter(item => item.type === 'asset').length;
-  }
-
-  // Cache key for search results
-  private readonly SEARCH_CACHE_KEY = '__search__';
-
-  async searchAssets(query: string): Promise<CloudinaryItem[]> {
-    try {
-      const maxResults = 500;
-      const searchQuery = cloudinary.search
-        .expression(`${query}*`)
-        .sort_by('created_at', this.viewState.sortDirection)
-        .max_results(maxResults);
-
-      const assetsResult = await searchQuery.execute();
-
-      const assets = assetsResult.resources.map(
-        (asset: any) =>
-          new CloudinaryItem(
-            asset.public_id,
-            vscode.TreeItemCollapsibleState.None,
-            'asset',
-            asset,
-            this.cloudName!,
-            this.dynamicFolders
-          )
-      );
-
-      // Store in cache
-      this.assetMap.set(this.SEARCH_CACHE_KEY, assets);
-
-      // If there are more results, start background pre-fetching
-      if (assetsResult.next_cursor) {
-        // Add loading indicator
-        const loadingItem = new CloudinaryItem(
-          'Loading more results...',
-          vscode.TreeItemCollapsibleState.None,
-          'loading',
-          { query }
-        );
-        this.assetMap.set(this.SEARCH_CACHE_KEY, [...assets, loadingItem]);
-
-        // Start background prefetch
-        this.prefetchSearchResults(query, assetsResult.next_cursor);
-      }
-
-      return this.assetMap.get(this.SEARCH_CACHE_KEY) || assets;
-    } catch (err: any) {
-      handleCloudinaryError('Search failed', err);
-      return [];
-    }
-  }
-
-  /**
-   * Background pre-fetches remaining search results.
-   */
-  private async prefetchSearchResults(query: string, initialCursor: string): Promise<void> {
-    const prefetchKey = `search:${query}`;
-
-    // Prevent duplicate prefetching
-    if (this.prefetchingFolders.has(prefetchKey)) {
-      return;
-    }
-    this.prefetchingFolders.add(prefetchKey);
-
-    try {
-      let nextCursor: string | null = initialCursor;
-      let totalAssets = this.countSearchResults();
-
-      while (nextCursor && totalAssets < this.MAX_ASSETS_PER_FOLDER) {
-        const result = await this.fetchSearchPage(query, nextCursor);
-
-        if (result.assets.length === 0) {
-          break;
-        }
-
-        // Append new assets to search cache
-        this.appendSearchResults(result.assets, result.nextCursor);
-        totalAssets += result.assets.length;
-        nextCursor = result.nextCursor;
-
-        // Fire tree update
-        this._onDidChangeTreeData.fire();
-      }
-
-      // Remove loading indicator
-      this.removeSearchLoadingIndicator();
-      this._onDidChangeTreeData.fire();
-    } catch (err: any) {
-      this.removeSearchLoadingIndicator();
-      this._onDidChangeTreeData.fire();
-      console.error('Search prefetch error:', err);
-    } finally {
-      this.prefetchingFolders.delete(prefetchKey);
-    }
-  }
-
-  /**
-   * Fetches a single page of search results.
-   */
-  private async fetchSearchPage(
-    query: string,
-    cursor: string
-  ): Promise<{ assets: CloudinaryItem[]; nextCursor: string | null }> {
-    const maxResults = 500;
-
-    const searchQuery = cloudinary.search
-      .expression(`${query}*`)
-      .sort_by('created_at', this.viewState.sortDirection)
-      .max_results(maxResults)
-      .next_cursor(cursor);
-
-    const assetsResult = await searchQuery.execute();
-
-    const assets = assetsResult.resources.map(
-      (asset: any) =>
-        new CloudinaryItem(
-          asset.public_id,
-          vscode.TreeItemCollapsibleState.None,
-          'asset',
-          asset,
-          this.cloudName!,
-          this.dynamicFolders
-        )
-    );
-
-    return {
-      assets,
-      nextCursor: assetsResult.next_cursor || null,
-    };
-  }
-
-  /**
-   * Appends prefetched search results to the cache.
-   */
-  private appendSearchResults(newAssets: CloudinaryItem[], hasMore: string | null): void {
-    const items = this.assetMap.get(this.SEARCH_CACHE_KEY) || [];
-
-    // Remove loading indicator
-    const filteredItems = items.filter(item => item.type !== 'loading');
-
-    // Append new assets
-    const updatedItems = [...filteredItems, ...newAssets];
-
-    // Add loading indicator back if more to fetch
-    if (hasMore) {
-      updatedItems.push(
-        new CloudinaryItem(
-          'Loading more results...',
-          vscode.TreeItemCollapsibleState.None,
-          'loading',
-          {}
-        )
-      );
-    }
-
-    this.assetMap.set(this.SEARCH_CACHE_KEY, updatedItems);
-  }
-
-  /**
-   * Removes the loading indicator from search results.
-   */
-  private removeSearchLoadingIndicator(): void {
-    const items = this.assetMap.get(this.SEARCH_CACHE_KEY);
-    if (!items) { return; }
-
-    const filteredItems = items.filter(item => item.type !== 'loading');
-    this.assetMap.set(this.SEARCH_CACHE_KEY, filteredItems);
-  }
-
-  /**
-   * Counts the number of search results currently loaded.
-   */
-  private countSearchResults(): number {
-    const items = this.assetMap.get(this.SEARCH_CACHE_KEY) || [];
-    return items.filter(item => item.type === 'asset').length;
-  }
-
-  /**
-   * Fetches available upload presets from Cloudinary.
-   * @returns Array of upload presets with their names and signed status.
-   */
-  async fetchUploadPresets(): Promise<Array<{
-    name: string;
-    signed: boolean;
-    settings?: {}
-  }>> {
-    if (!this.cloudName || !this.apiKey || !this.apiSecret) {
-      throw new Error('Cloudinary credentials not configured');
-    }
-
-    try {
-      const result = await cloudinary.api.upload_presets({ max_results: 500 });
-      this.uploadPresets = result.presets.map((preset: any) => ({
-        name: preset.name,
-        signed: preset.unsigned === false,
-        settings: preset.settings
-      }));
-      return this.uploadPresets;
-    } catch (err: any) {
-      handleCloudinaryError('Failed to fetch upload presets', err);
-      return [];
-    }
-  }
-
-  /**
-   * Gets the currently configured default upload preset.
-   * @returns The configured upload preset name, or null if none configured (uses signed upload).
-   */
-  getCurrentUploadPreset(): string | null {
-    // Only return a preset if one is explicitly configured and exists
-    if (this.uploadPreset && this.uploadPresets.some(p => p.name === this.uploadPreset)) {
-      return this.uploadPreset;
-    }
-    // Default to null (signed upload) when no preset is configured
-    return null;
-  }
-
-  /**
-   * Gets all folder paths that have been loaded/cached.
-   * Returns folder items from the assetMap for use in folder selectors.
-   */
-  public getAvailableFolders(): Array<{ path: string; name: string }> {
-    const folders: Array<{ path: string; name: string }> = [];
-
-    for (const [, items] of this.assetMap.entries()) {
-      for (const item of items) {
-        if (item.type === 'folder') {
-          // FolderData has path and name properties
-          const folderData = item.data as { path?: string; name?: string };
-          if (folderData.path) {
-            folders.push({
-              path: folderData.path,
-              name: folderData.name || item.label?.toString() || folderData.path,
-            });
-          }
-        }
-      }
-    }
-
-    // Sort by path for consistent ordering
-    return folders.sort((a, b) => a.path.localeCompare(b.path));
-  }
-}
diff --git a/src/utils/aiToolsGuidance.ts b/src/utils/aiToolsGuidance.ts
new file mode 100644
index 0000000..627abd6
--- /dev/null
+++ b/src/utils/aiToolsGuidance.ts
@@ -0,0 +1,36 @@
+/**
+ * Builds the post-install guidance message shown after "Configure AI Tools"
+ * applies. Returns null when nothing was installed.
+ *
+ * MCP servers only take effect after the editor reloads; without spelling that
+ * out, users see them as "configured" but not connected in their AI tool, so the
+ * message includes an explicit reload/verify step whenever an MCP server landed.
+ */
+export function buildAiToolsNextStepsMessage(
+  installedSkillsCount: number,
+  installedMcpCount: number,
+  mcpEditorLabel?: string
+): string | null {
+  if (installedSkillsCount <= 0 && installedMcpCount <= 0) {
+    return null;
+  }
+
+  const parts: string[] = [];
+  if (installedSkillsCount > 0) {
+    parts.push(`${installedSkillsCount} skill${installedSkillsCount === 1 ? "" : "s"}`);
+  }
+  if (installedMcpCount > 0) {
+    parts.push(`${installedMcpCount} MCP server${installedMcpCount === 1 ? "" : "s"}`);
+  }
+  const what = parts.join(" and ");
+
+  const editorName = mcpEditorLabel ?? "your editor";
+  const nextStep =
+    installedMcpCount > 0
+      ? ` Reload ${editorName} (Developer: Reload Window) and start a new chat so the MCP server${
+          installedMcpCount === 1 ? "" : "s"
+        } connect — until then they show as configured but inactive.`
+      : "";
+
+  return `Cloudinary: installed ${what}.${nextStep}`;
+}
diff --git a/src/utils/cloudinaryErrorHandler.ts b/src/utils/cloudinaryErrorHandler.ts
index 3d9ddc2..3ed7703 100644
--- a/src/utils/cloudinaryErrorHandler.ts
+++ b/src/utils/cloudinaryErrorHandler.ts
@@ -1,6 +1,24 @@
 import * as vscode from 'vscode';
 import { getGlobalConfigPath } from '../config/configUtils';
 
+/**
+ * Whether a Cloudinary error was caused by invalid/unauthorized credentials
+ * (bad cloud name, API key, or secret) rather than some other failure.
+ */
+export function isCredentialError(error: any): boolean {
+    const httpCode = error?.error?.http_code ?? error?.http_code ?? error?.response?.status;
+    if (httpCode === 401 || httpCode === 403) {
+        return true;
+    }
+    const message =
+        (typeof error?.message === 'string' && error.message) ||
+        (typeof error?.error?.message === 'string' && error.error.message) ||
+        '';
+    return /invalid signature|api key|api secret|unknown api key|disabled account|unauthorized|invalid credentials/i.test(
+        message
+    );
+}
+
 export async function handleCloudinaryError(context: string, error: any) {
     const extractMessage = (err: any): string => {
         if (!err) {return 'Unknown error';}
@@ -15,7 +33,11 @@ export async function handleCloudinaryError(context: string, error: any) {
         return JSON.stringify(err, null, 2).slice(0, 200); // fallback: stringify safely
     };
 
-    const message = `${context}: ${extractMessage(error)}. Fix your config and reselect an environment.`;
+    // Credential failures get a clearer, actionable message instead of a raw
+    // SDK error, since the fix is almost always "correct your credentials".
+    const message = isCredentialError(error)
+        ? `${context}: your Cloudinary credentials appear to be invalid or unauthorized. Check the cloud name, API key, and API secret in your config.`
+        : `${context}: ${extractMessage(error)}. Fix your config and reselect an environment.`;
     const choice = await vscode.window.showErrorMessage(message, 'Open Global Config');
 
     if (choice === 'Open Global Config') {
diff --git a/src/webview/client/actionToolbar.ts b/src/webview/client/actionToolbar.ts
new file mode 100644
index 0000000..58a6f43
--- /dev/null
+++ b/src/webview/client/actionToolbar.ts
@@ -0,0 +1,24 @@
+export type ActionToolbarAction =
+  | "showHomescreen"
+  | "refresh"
+  | "openUploadWidget"
+  | "openGlobalConfig";
+
+interface InitActionToolbarOptions {
+  onAction: (action: ActionToolbarAction) => void;
+  root?: ParentNode;
+}
+
+export function initActionToolbar(options: InitActionToolbarOptions): void {
+  const root = options.root ?? document;
+  root
+    .querySelectorAll<HTMLButtonElement>("[data-cld-action-toolbar] [data-action]")
+    .forEach((button) => {
+      button.addEventListener("click", () => {
+        const action = button.dataset.action as ActionToolbarAction | undefined;
+        if (action) {
+          options.onAction(action);
+        }
+      });
+    });
+}
diff --git a/src/webview/client/docs-ai.ts b/src/webview/client/docs-ai.ts
new file mode 100644
index 0000000..6c1cba9
--- /dev/null
+++ b/src/webview/client/docs-ai.ts
@@ -0,0 +1 @@
+import "./docs-ai/webview";
diff --git a/src/webview/client/docs-ai/db.ts b/src/webview/client/docs-ai/db.ts
new file mode 100644
index 0000000..f09b658
--- /dev/null
+++ b/src/webview/client/docs-ai/db.ts
@@ -0,0 +1,143 @@
+// @ts-nocheck
+
+const DB_NAME = 'CloudinaryVSCodeChatDB'
+const DB_VERSION = 2
+
+function openDB() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION)
+    req.onupgradeneeded = (e) => {
+      const db = e.target.result
+      const oldVersion = e.oldVersion
+      if (oldVersion < 1) {
+        const convStore = db.createObjectStore('conversations', { keyPath: 'id' })
+        convStore.createIndex('updatedAt', 'updatedAt', { unique: false })
+        const msgStore = db.createObjectStore('messages', { keyPath: 'id' })
+        msgStore.createIndex('conversationId', 'conversationId', { unique: false })
+      }
+      if (oldVersion < 2) {
+        db.createObjectStore('tabState', { keyPath: 'id' })
+      }
+    }
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error)
+  })
+}
+
+export async function dbGetAllConversations() {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('conversations', 'readonly')
+    const req = tx.objectStore('conversations').getAll()
+    req.onsuccess = () => {
+      const list = req.result || []
+      list.sort((a, b) => b.updatedAt - a.updatedAt)
+      resolve(list)
+    }
+    req.onerror = () => reject(req.error)
+  })
+}
+
+export async function dbGetMessages(conversationId) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('messages', 'readonly')
+    const req = tx.objectStore('messages').index('conversationId').getAll(conversationId)
+    req.onsuccess = () => {
+      const list = req.result || []
+      list.sort((a, b) => a.createdAt - b.createdAt)
+      resolve(list)
+    }
+    req.onerror = () => reject(req.error)
+  })
+}
+
+export async function dbSaveConversation(conv) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('conversations', 'readwrite')
+    tx.objectStore('conversations').put(conv)
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+}
+
+export async function dbSaveMessage(msg) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('messages', 'readwrite')
+    tx.objectStore('messages').put(msg)
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+}
+
+export async function dbDeleteConversation(id) {
+  const db = await openDB()
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction('conversations', 'readwrite')
+    tx.objectStore('conversations').delete(id)
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+  const msgs = await dbGetMessages(id)
+  if (msgs.length > 0) {
+    const db2 = await openDB()
+    await new Promise((resolve, reject) => {
+      const tx = db2.transaction('messages', 'readwrite')
+      const store = tx.objectStore('messages')
+      for (const m of msgs) {store.delete(m.id)}
+      tx.oncomplete = () => resolve()
+      tx.onerror = () => reject(tx.error)
+    })
+  }
+}
+
+export async function dbClearChatState() {
+  const db = await openDB()
+  const stores = ['conversations', 'messages', 'tabState'].filter(storeName => db.objectStoreNames.contains(storeName))
+  if (stores.length === 0) {return}
+
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction(stores, 'readwrite')
+    for (const storeName of stores) {
+      tx.objectStore(storeName).clear()
+    }
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+}
+
+export async function dbDeleteMessagesAfter(conversationId, createdAtCutoff) {
+  const msgs = await dbGetMessages(conversationId)
+  const toDelete = msgs.filter(m => m.createdAt > createdAtCutoff)
+  if (toDelete.length === 0) {return}
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('messages', 'readwrite')
+    const store = tx.objectStore('messages')
+    for (const m of toDelete) {store.delete(m.id)}
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+}
+
+export async function dbSaveTabState(tabState) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('tabState', 'readwrite')
+    tx.objectStore('tabState').put({ id: 'current', ...tabState })
+    tx.oncomplete = () => resolve()
+    tx.onerror = () => reject(tx.error)
+  })
+}
+
+export async function dbLoadTabState() {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('tabState', 'readonly')
+    const req = tx.objectStore('tabState').get('current')
+    req.onsuccess = () => resolve(req.result || null)
+    req.onerror = () => reject(req.error)
+  })
+}
diff --git a/src/webview/client/docs-ai/history.ts b/src/webview/client/docs-ai/history.ts
new file mode 100644
index 0000000..72c912e
--- /dev/null
+++ b/src/webview/client/docs-ai/history.ts
@@ -0,0 +1,200 @@
+// @ts-nocheck
+
+import { state, $, escapeHtml, timeAgo, callbacks } from "./state"
+import { dbSaveConversation } from "./db"
+import { loadConversation, deleteConversation, renderTabBar, persistTabState, confirmClearAllChats } from "./tabs"
+
+let historySearch = ''
+let renamingId = null
+
+export function groupConversationsByDate(convs) {
+  const now = new Date()
+  const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime()
+  const yesterdayStart = todayStart - 86400000
+  const weekStart = todayStart - 6 * 86400000
+
+  const groups = []
+  const today = [], yesterday = [], week = [], older = []
+
+  for (const c of convs) {
+    if (c.updatedAt >= todayStart) {today.push(c)}
+    else if (c.updatedAt >= yesterdayStart) {yesterday.push(c)}
+    else if (c.updatedAt >= weekStart) {week.push(c)}
+    else {older.push(c)}
+  }
+
+  if (today.length) {groups.push({ label: 'Today', items: today })}
+  if (yesterday.length) {groups.push({ label: 'Yesterday', items: yesterday })}
+  if (week.length) {groups.push({ label: 'Previous 7 days', items: week })}
+  if (older.length) {groups.push({ label: 'Older', items: older })}
+  return groups
+}
+
+export function toggleHistoryDropdown() {
+  state.historyOpen = !state.historyOpen
+  historySearch = ''
+  renamingId = null
+  renderHistoryDropdown()
+}
+
+export function renderHistoryDropdown() {
+  const dropdown = $('#history-dropdown')
+  if (!dropdown) {return}
+
+  if (!state.historyOpen) {
+    dropdown.style.display = 'none'
+    return
+  }
+
+  dropdown.style.display = 'flex'
+
+  const filtered = historySearch
+    ? state.conversations.filter(c => c.title.toLowerCase().includes(historySearch.toLowerCase()))
+    : state.conversations
+
+  let bodyHtml = ''
+
+  if (filtered.length === 0) {
+    bodyHtml = `<div class="history-empty">${historySearch ? 'No matching chats' : 'No previous chats'}</div>`
+  } else {
+    const groups = groupConversationsByDate(filtered)
+    bodyHtml = groups.map(g => `
+      <div class="history-group">
+        <div class="history-group-label">${g.label}</div>
+        ${g.items.map(c => renderHistoryItem(c)).join('')}
+      </div>
+    `).join('')
+  }
+
+  const clearAllHtml = state.conversations.length > 0 ? `
+    <div class="history-footer">
+      <button id="history-clear-all" class="history-clear-all" type="button">
+        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6"/><path d="M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/></svg>
+        <span>Clear all chats</span>
+      </button>
+    </div>
+  ` : ''
+
+  dropdown.innerHTML = `
+    <div class="history-search-row">
+      <input id="history-search" class="history-search" type="text" placeholder="Search..." value="${escapeHtml(historySearch)}" />
+    </div>
+    <div class="history-list">${bodyHtml}</div>
+    ${clearAllHtml}
+  `
+
+  attachDropdownListeners()
+
+  const searchEl = dropdown.querySelector('#history-search')
+  if (searchEl && !historySearch) {searchEl.focus()}
+}
+
+function renderHistoryItem(c) {
+  const isActive = c.id === state.currentConversationId
+  const isRenaming = c.id === renamingId
+
+  if (isRenaming) {
+    return `
+      <div class="history-item active" data-conv-id="${c.id}">
+        <input class="history-rename-input" data-conv-id="${c.id}" type="text" value="${escapeHtml(c.title)}" />
+        <button class="history-action history-rename-confirm" data-conv-id="${c.id}" title="Save">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+        </button>
+      </div>`
+  }
+
+  return `
+    <div class="history-item ${isActive ? 'active' : ''}" data-conv-id="${c.id}">
+      <span class="history-title">${escapeHtml(c.title)}</span>
+      <span class="history-time">${timeAgo(c.updatedAt)}</span>
+      <div class="history-actions">
+        <button class="history-action history-rename-btn" data-conv-id="${c.id}" title="Rename">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"/></svg>
+        </button>
+        <button class="history-action history-delete" data-conv-id="${c.id}" title="Delete">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6"/><path d="M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/></svg>
+        </button>
+      </div>
+    </div>`
+}
+
+function attachDropdownListeners() {
+  const dropdown = $('#history-dropdown')
+  if (!dropdown) {return}
+
+  const searchInput = dropdown.querySelector('#history-search')
+  if (searchInput) {
+    searchInput.addEventListener('input', (e) => {
+      historySearch = e.target.value
+      renderHistoryDropdown()
+      const newInput = $('#history-search')
+      if (newInput) { newInput.focus(); newInput.selectionStart = newInput.selectionEnd = newInput.value.length }
+    })
+  }
+
+  dropdown.querySelector('#history-clear-all')?.addEventListener('click', (e) => {
+    e.stopPropagation()
+    confirmClearAllChats()
+  })
+
+  dropdown.querySelectorAll('.history-item').forEach(item => {
+    item.addEventListener('click', (e) => {
+      if (e.target.closest('.history-action') || e.target.closest('.history-rename-input')) {return}
+      loadConversation(item.dataset.convId)
+    })
+  })
+
+  dropdown.querySelectorAll('.history-delete').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation()
+      deleteConversation(btn.dataset.convId)
+    })
+  })
+
+  dropdown.querySelectorAll('.history-rename-btn').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation()
+      renamingId = btn.dataset.convId
+      renderHistoryDropdown()
+      const renameInput = dropdown.querySelector(`.history-rename-input[data-conv-id="${renamingId}"]`)
+      if (renameInput) { renameInput.focus(); renameInput.select() }
+    })
+  })
+
+  dropdown.querySelectorAll('.history-rename-confirm').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation()
+      const input = dropdown.querySelector(`.history-rename-input[data-conv-id="${btn.dataset.convId}"]`)
+      if (input) {confirmRename(btn.dataset.convId, input.value)}
+    })
+  })
+
+  dropdown.querySelectorAll('.history-rename-input').forEach(input => {
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') {
+        e.preventDefault()
+        confirmRename(input.dataset.convId, input.value)
+      } else if (e.key === 'Escape') {
+        renamingId = null
+        renderHistoryDropdown()
+      }
+    })
+  })
+}
+
+export async function confirmRename(id, newTitle) {
+  const title = newTitle.trim()
+  if (!title) {return}
+  const conv = state.conversations.find(c => c.id === id)
+  if (conv) {
+    conv.title = title
+    try { await dbSaveConversation(conv) } catch (e) { console.error('Failed to rename conversation:', e) }
+  }
+  const tab = state.openTabs.find(t => t.conversationId === id)
+  if (tab) {tab.title = title}
+  renamingId = null
+  renderHistoryDropdown()
+  renderTabBar()
+  callbacks.syncRecentConversations()
+  persistTabState()
+}
diff --git a/src/webview/client/docs-ai/markdown.ts b/src/webview/client/docs-ai/markdown.ts
new file mode 100644
index 0000000..cd49f9a
--- /dev/null
+++ b/src/webview/client/docs-ai/markdown.ts
@@ -0,0 +1,292 @@
+// @ts-nocheck
+
+import { marked } from 'marked'
+import hljs from 'highlight.js/lib/common'
+
+marked.setOptions({ breaks: true, gfm: true })
+const renderer = new marked.Renderer()
+
+const allowedTags = new Set([
+  'a', 'blockquote', 'br', 'button', 'code', 'del', 'div', 'em', 'h1', 'h2',
+  'h3', 'h4', 'h5', 'h6', 'hr', 'li', 'ol', 'p', 'pre', 'span', 'strong',
+  'table', 'tbody', 'td', 'th', 'thead', 'tr', 'ul',
+])
+const removeWithChildren = new Set([
+  'audio', 'canvas', 'embed', 'form', 'iframe', 'img', 'input', 'math', 'object',
+  'script', 'select', 'style', 'svg', 'textarea', 'video',
+])
+const allowedAttrs = {
+  a: new Set(['class', 'href', 'rel', 'target', 'title']),
+  button: new Set(['aria-label', 'class', 'data-code', 'title', 'type']),
+  code: new Set(['class']),
+  div: new Set(['class']),
+  pre: new Set(['class']),
+  span: new Set(['class']),
+  th: new Set(['align']),
+  td: new Set(['align']),
+}
+const allowedClassNames = new Set([
+  'code-block', 'code-copy', 'code-header', 'code-lang', 'doc-citation', 'hljs',
+])
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function escapeAttribute(value) {
+  return escapeHtml(value).replace(/`/g, '&#96;')
+}
+
+function safeLanguageToken(value) {
+  const token = String(value || '').trim()
+  return /^[a-zA-Z0-9_-]+$/.test(token) ? token : ''
+}
+
+function sanitizeClassList(value) {
+  return String(value || '')
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((name) => allowedClassNames.has(name) || name.startsWith('hljs-') || name.startsWith('language-'))
+    .join(' ')
+}
+
+function isSafeUrl(value) {
+  try {
+    const url = new URL(value, 'https://cloudinary.com')
+    return url.protocol === 'https:' || url.protocol === 'http:'
+  } catch (_) {
+    return false
+  }
+}
+
+function unwrapElement(element) {
+  const parent = element.parentNode
+  if (!parent) {return}
+  while (element.firstChild) {
+    parent.insertBefore(element.firstChild, element)
+  }
+  element.remove()
+}
+
+function sanitizeElement(element) {
+  const tag = element.tagName.toLowerCase()
+
+  if (removeWithChildren.has(tag)) {
+    element.remove()
+    return
+  }
+
+  if (!allowedTags.has(tag)) {
+    unwrapElement(element)
+    return
+  }
+
+  Array.from(element.attributes).forEach((attr) => {
+    const name = attr.name.toLowerCase()
+    const allowedForTag = allowedAttrs[tag]
+
+    if (!allowedForTag?.has(name)) {
+      element.removeAttribute(attr.name)
+      return
+    }
+
+    if (name === 'class') {
+      const safeClass = sanitizeClassList(attr.value)
+      if (safeClass) {
+        element.setAttribute('class', safeClass)
+      } else {
+        element.removeAttribute('class')
+      }
+      return
+    }
+
+    if (tag === 'a' && name === 'href' && !isSafeUrl(attr.value)) {
+      element.removeAttribute('href')
+    }
+  })
+
+  if (tag === 'a' && element.hasAttribute('href')) {
+    element.setAttribute('target', '_blank')
+    element.setAttribute('rel', 'noopener noreferrer')
+  }
+
+  if (tag === 'button') {
+    if (!element.classList.contains('code-copy')) {
+      unwrapElement(element)
+      return
+    }
+    element.setAttribute('type', 'button')
+    element.setAttribute('aria-label', 'Copy code')
+  }
+}
+
+function sanitizeMarkdownHtml(html) {
+  const template = document.createElement('template')
+  template.innerHTML = html
+
+  const walker = document.createTreeWalker(template.content, NodeFilter.SHOW_ELEMENT)
+  const elements = []
+  let node = walker.nextNode()
+  while (node) {
+    elements.push(node)
+    node = walker.nextNode()
+  }
+
+  elements.forEach((element) => sanitizeElement(element))
+  return template.innerHTML
+}
+
+renderer.link = function ({ href, title, text }) {
+  const t = title ? ` title="${escapeAttribute(title)}"` : ''
+  return `<a href="${escapeAttribute(href || '')}"${t} target="_blank" rel="noopener noreferrer">${text}</a>`
+}
+renderer.code = function ({ text, lang }) {
+  let highlighted
+  let displayLang = lang || ''
+  const safeLang = safeLanguageToken(lang)
+  if (lang && hljs.getLanguage(lang)) {
+    try {
+      highlighted = hljs.highlight(text, { language: lang }).value
+    } catch (_) {
+      const auto = hljs.highlightAuto(text)
+      highlighted = auto.value
+      if (!displayLang && auto.language) {displayLang = auto.language}
+    }
+  } else {
+    const auto = hljs.highlightAuto(text)
+    highlighted = auto.value
+    if (!displayLang && auto.language) {displayLang = auto.language}
+  }
+
+  const langLabel = displayLang ? `<span class="code-lang">${escapeHtml(displayLang)}</span>` : ''
+  const escapedText = escapeAttribute(text)
+
+  return `<div class="code-block">
+    <div class="code-header">
+      ${langLabel}
+      <button class="code-copy" type="button" data-code="${escapedText}" title="Copy code" aria-label="Copy code">
+        <span>Copy</span>
+      </button>
+    </div>
+    <pre><code class="hljs${safeLang ? ` language-${safeLang}` : ''}">${highlighted}</code></pre>
+  </div>`
+}
+
+function sourcePath(source) {
+  if (typeof source === 'string') {return source}
+  return source?.path || source?.source || source?.id || source?.slug || source?.url || ''
+}
+
+function sourceSlug(source) {
+  const path = sourcePath(source)
+  try {
+    const url = new URL(path)
+    const match = url.pathname.match(/\/documentation\/([^/#?]+)/)
+    if (match) {return match[1]}
+  } catch (_) {}
+
+  return path
+    .replace(/^https?:\/\/(?:www\.)?cloudinary\.com\/documentation\//, '')
+    .replace(/^content\/documentation\//, '')
+    .replace(/\.html\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/^\/+|\/+$/g, '')
+}
+
+function sourceUrl(source) {
+  if (source && typeof source === 'object' && source.url) {return source.url}
+  const slug = sourceSlug(source)
+  return `https://cloudinary.com/documentation/${slug}`
+}
+
+function sourceLabel(source) {
+  if (source && typeof source === 'object' && source.title) {return source.title}
+  const label = sourceSlug(source).replace(/_/g, ' ')
+  return label.charAt(0).toUpperCase() + label.slice(1)
+}
+
+function sourceAliases(source) {
+  const path = sourcePath(source)
+  const slug = sourceSlug(source)
+  const basename = slug.split('/').pop() || slug
+  return [
+    path,
+    slug,
+    basename,
+    `${slug}.md`,
+    `${basename}.md`,
+    `${slug}.html.md`,
+    `${basename}.html.md`,
+    `content/documentation/${slug}.html.md`,
+    `content/documentation/${basename}.html.md`,
+  ].filter(Boolean)
+}
+
+function normalizeAlias(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^`|`$/g, '')
+    .replace(/^["']|["']$/g, '')
+    .replace(/^https?:\/\/(?:www\.)?cloudinary\.com\/documentation\//, '')
+    .replace(/^content\/documentation\//, '')
+    .replace(/\.html\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/^\/+|\/+$/g, '')
+    .toLowerCase()
+}
+
+function buildCitationMap(sources) {
+  const map = new Map()
+  ;(sources || []).forEach((source, index) => {
+    sourceAliases(source).forEach(alias => {
+      map.set(normalizeAlias(alias), { index: index + 1, source })
+    })
+  })
+  return map
+}
+
+function citationHtml(citation) {
+  const href = escapeAttribute(sourceUrl(citation.source))
+  const title = escapeAttribute(sourceLabel(citation.source))
+  return `<a class="doc-citation" href="${href}" title="${title}" target="_blank" rel="noopener noreferrer">[${citation.index}]</a>`
+}
+
+function replaceInlineCitations(content, sources) {
+  const citationMap = buildCitationMap(sources)
+  if (!citationMap.size) {return content}
+
+  let processed = content.replace(/\(([^()\n]{3,240})\)/g, (match, inner) => {
+    const parts = inner.split(',').map(part => part.trim()).filter(Boolean)
+    if (!parts.length) {return match}
+
+    const citations = parts.map(part => citationMap.get(normalizeAlias(part)))
+    if (citations.some(citation => !citation)) {return match}
+
+    const unique = []
+    const seen = new Set()
+    citations.forEach(citation => {
+      if (seen.has(citation.index)) {return}
+      seen.add(citation.index)
+      unique.push(citation)
+    })
+
+    return unique.map(citationHtml).join(' ')
+  })
+
+  processed = processed.replace(
+    /content\/documentation\/([a-zA-Z0-9_/-]+)\.html\.md|([a-zA-Z0-9_/-]+)\.md/g,
+    (match) => citationMap.has(normalizeAlias(match)) ? citationHtml(citationMap.get(normalizeAlias(match))) : match
+  )
+
+  return processed
+}
+
+export function renderMarkdown(content, sources = []) {
+  const processed = replaceInlineCitations(content, sources)
+  try { return sanitizeMarkdownHtml(marked(processed, { renderer })) } catch (_) { return escapeHtml(content) }
+}
diff --git a/src/webview/client/docs-ai/state.ts b/src/webview/client/docs-ai/state.ts
new file mode 100644
index 0000000..79cf80c
--- /dev/null
+++ b/src/webview/client/docs-ai/state.ts
@@ -0,0 +1,183 @@
+// @ts-nocheck
+
+const DEFAULT_API_BASE = 'https://cld-docs-ai-delta.vercel.app'
+
+function normalizeApiBase(value) {
+  const rawValue = typeof value === 'string' ? value.trim() : ''
+  if (!rawValue) {return DEFAULT_API_BASE}
+
+  try {
+    const url = new URL(rawValue)
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {return DEFAULT_API_BASE}
+    url.hash = ''
+    url.search = ''
+    return url.href.replace(/\/+$/, '')
+  } catch (_) {
+    return DEFAULT_API_BASE
+  }
+}
+
+export const API_BASE = normalizeApiBase(
+  typeof window !== 'undefined' ? window.__DOCS_AI_API_BASE__ : DEFAULT_API_BASE
+)
+export const API_URL = `${API_BASE}/api/rag/chat-ai`
+export const vscode = acquireVsCodeApi()
+
+const rawIdeName = (typeof window !== 'undefined' && window.__IDE_NAME__) || 'vscode'
+export const IDE_PLATFORM = rawIdeName.toLowerCase().replace(/\s+/g, '-')
+export const INITIAL_PROMPT =
+  typeof window !== 'undefined' && typeof window.__INITIAL_PROMPT__ === 'string'
+    ? window.__INITIAL_PROMPT__.trim()
+    : ''
+export const INITIAL_CONVERSATION_ID =
+  typeof window !== 'undefined' && typeof window.__INITIAL_CONVERSATION_ID__ === 'string'
+    ? window.__INITIAL_CONVERSATION_ID__.trim()
+    : ''
+
+export const state = {
+  messages: [],
+  conversations: [],
+  currentConversationId: null,
+  streaming: false,
+  loading: false,
+  abortController: null,
+  shouldAutoScroll: true,
+  isAutoScrolling: false,
+  historyOpen: false,
+  openTabs: [],
+  activeTabId: null,
+}
+
+export const tabMessagesCache = new Map()
+export const tabStreamState = new Map()
+
+export const starterQuestions = [
+  'What\'s new in Cloudinary?',
+  'How do I upload images?',
+  'Explain image transformations',
+  'How do I optimize videos?',
+  'What SDKs does Cloudinary support?',
+  'How do I resize images?',
+  'What is the Media Library?',
+  'How do I crop images?',
+  'What is DAM?',
+]
+
+export function pickStarters(n) {
+  const s = [...starterQuestions].sort(() => Math.random() - 0.5)
+  return s.slice(0, n)
+}
+
+export function uid() {
+  return 'msg-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8)
+}
+
+export function convId() {
+  return 'conv-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8)
+}
+
+export function tabId() {
+  return 'tab-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8)
+}
+
+export const $ = (sel) => document.querySelector(sel)
+export const conversationEl = () => $('#conversation')
+export const inputEl = () => $('#chat-input')
+
+let autoScrollToken = 0
+
+export function scrollToBottom() {
+  if (!state.shouldAutoScroll) {return}
+  const conv = conversationEl()
+  if (!conv) {return}
+
+  const token = ++autoScrollToken
+  state.isAutoScrolling = true
+
+  const pinToBottom = () => {
+    conv.scrollTop = conv.scrollHeight
+  }
+
+  pinToBottom()
+  requestAnimationFrame(pinToBottom)
+
+  setTimeout(() => {
+    if (token === autoScrollToken) {state.isAutoScrolling = false}
+  }, 120)
+}
+
+export function normalizeSources(payload) {
+  if (!Array.isArray(payload)) {return []}
+  return payload.map(item => {
+    if (typeof item === 'string') {return { path: item }}
+    if (item && typeof item === 'object') {
+      const path = item.path || item.source || item.id || item.slug || item.title || item.url || null
+      if (!path) {return null}
+      return {
+        path,
+        title: item.title || item.name || item.label || '',
+        url: item.url || item.href || '',
+      }
+    }
+    return null
+  }).filter(Boolean)
+}
+
+export function getSourcePath(source) {
+  if (typeof source === 'string') {return source}
+  return source?.path || source?.source || source?.id || source?.slug || source?.url || ''
+}
+
+export function getSourceSlug(source) {
+  const path = getSourcePath(source)
+  try {
+    const url = new URL(path)
+    const docMatch = url.pathname.match(/\/documentation\/([^/#?]+)/)
+    if (docMatch) {return docMatch[1]}
+  } catch (_) {}
+
+  return path
+    .replace(/^https?:\/\/(?:www\.)?cloudinary\.com\/documentation\//, '')
+    .replace(/^content\/documentation\//, '')
+    .replace(/\.html\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/^\/+|\/+$/g, '')
+}
+
+export function getSourceUrl(source) {
+  if (source && typeof source === 'object' && source.url) {return source.url}
+  const d = getSourceSlug(source)
+  return `https://cloudinary.com/documentation/${d}`
+}
+
+export function getSourceLabel(source) {
+  if (source && typeof source === 'object' && source.title) {return source.title}
+  const label = getSourceSlug(source).replace(/_/g, ' ')
+  return label.charAt(0).toUpperCase() + label.slice(1)
+}
+
+export function escapeHtml(str) {
+  const d = document.createElement('div')
+  d.textContent = str
+  return d.innerHTML
+}
+
+export function timeAgo(ts) {
+  const seconds = Math.floor((Date.now() - ts) / 1000)
+  if (seconds < 60) {return 'just now'}
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) {return `${minutes}m`}
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) {return `${hours}h`}
+  const days = Math.floor(hours / 24)
+  if (days < 30) {return `${days}d`}
+  return new Date(ts).toLocaleDateString()
+}
+
+// Callbacks set by webview.js to break circular deps
+export const callbacks = {
+  render: () => {},
+  renderHistoryDropdown: () => {},
+  syncRecentConversations: () => {},
+  trackAnalytics: () => {},
+}
diff --git a/src/webview/client/docs-ai/tabs.ts b/src/webview/client/docs-ai/tabs.ts
new file mode 100644
index 0000000..01771ec
--- /dev/null
+++ b/src/webview/client/docs-ai/tabs.ts
@@ -0,0 +1,419 @@
+// @ts-nocheck
+
+import { state, tabMessagesCache, tabStreamState, $, escapeHtml, tabId, callbacks } from "./state"
+import { dbGetMessages, dbSaveConversation, dbSaveMessage, dbDeleteConversation, dbGetAllConversations, dbSaveTabState, dbClearChatState } from "./db"
+
+const MAX_CONVERSATIONS = 50
+
+function showClearChatsConfirmation(onConfirm) {
+  document.querySelector('.docs-ai-confirm-overlay')?.remove()
+
+  const previouslyFocused = document.activeElement instanceof HTMLElement
+    ? document.activeElement
+    : null
+  const overlay = document.createElement('div')
+  overlay.className = 'docs-ai-confirm-overlay'
+  overlay.setAttribute('role', 'presentation')
+  overlay.innerHTML = `
+    <div class="docs-ai-confirm-dialog" role="dialog" aria-modal="true" aria-labelledby="docs-ai-confirm-title" aria-describedby="docs-ai-confirm-message">
+      <h2 id="docs-ai-confirm-title" class="docs-ai-confirm-title">Delete all conversations?</h2>
+      <p id="docs-ai-confirm-message" class="docs-ai-confirm-message">This will permanently remove all chat history.</p>
+      <div class="docs-ai-confirm-actions">
+        <button class="docs-ai-confirm-btn docs-ai-confirm-cancel" type="button">Cancel</button>
+        <button class="docs-ai-confirm-btn docs-ai-confirm-delete" type="button">Delete All</button>
+      </div>
+    </div>
+  `
+
+  const cancelButton = overlay.querySelector('.docs-ai-confirm-cancel')
+  const deleteButton = overlay.querySelector('.docs-ai-confirm-delete')
+  if (!cancelButton || !deleteButton) {return}
+
+  function close() {
+    document.removeEventListener('keydown', handleKeydown)
+    overlay.remove()
+    previouslyFocused?.focus()
+  }
+
+  function handleKeydown(event) {
+    if (event.key === 'Escape') {
+      close()
+    }
+  }
+
+  cancelButton.addEventListener('click', close)
+  deleteButton.addEventListener('click', () => {
+    close()
+    onConfirm()
+  })
+  overlay.addEventListener('mousedown', (event) => {
+    if (event.target === overlay) {
+      close()
+    }
+  })
+
+  document.body.appendChild(overlay)
+  document.addEventListener('keydown', handleKeydown)
+  requestAnimationFrame(() => overlay.classList.add('is-visible'))
+  cancelButton.focus()
+}
+
+// --- Persistence helpers ---
+
+export async function persistMessage(msg) {
+  if (!state.currentConversationId) {return}
+  try {
+    await dbSaveMessage({ ...msg, conversationId: state.currentConversationId, streaming: false })
+  } catch (e) {
+    console.error('Failed to persist message:', e)
+  }
+}
+
+export async function updateConversationTimestamp() {
+  if (!state.currentConversationId) {return}
+  const conv = state.conversations.find(c => c.id === state.currentConversationId)
+  if (conv) {
+    conv.updatedAt = Date.now()
+    try { await dbSaveConversation(conv) } catch (e) { console.error('Failed to update conversation:', e) }
+    callbacks.syncRecentConversations()
+  }
+}
+
+export async function persistTabState() {
+  try {
+    await dbSaveTabState({ openTabs: state.openTabs, activeTabId: state.activeTabId })
+  } catch (e) {
+    console.error('Failed to persist tab state:', e)
+  }
+}
+
+export async function loadConversations() {
+  try {
+    state.conversations = await dbGetAllConversations()
+    await enforceConversationLimit()
+    callbacks.syncRecentConversations()
+  } catch (e) {
+    console.error('Failed to load conversations:', e)
+    state.conversations = []
+  }
+}
+
+export async function enforceConversationLimit() {
+  if (state.conversations.length <= MAX_CONVERSATIONS) {return}
+  const openConvIds = new Set(state.openTabs.map(t => t.conversationId).filter(Boolean))
+  const toRemove = []
+  for (let i = state.conversations.length - 1; i >= 0 && state.conversations.length - toRemove.length > MAX_CONVERSATIONS; i--) {
+    if (!openConvIds.has(state.conversations[i].id)) {toRemove.push(state.conversations[i].id)}
+  }
+  for (const id of toRemove) {
+    try { await dbDeleteConversation(id) } catch (_) {}
+    state.conversations = state.conversations.filter(c => c.id !== id)
+  }
+  callbacks.syncRecentConversations()
+}
+
+// --- Tab management ---
+
+export function createTab(conversationId, title) {
+  const id = tabId()
+  const tab = { id, conversationId, title: title || 'New Chat' }
+  state.openTabs.push(tab)
+  state.activeTabId = id
+  return tab
+}
+
+export async function switchTab(tid) {
+  if (tid === state.activeTabId) {return}
+
+  tabMessagesCache.set(state.activeTabId, state.messages)
+
+  state.activeTabId = tid
+  const tab = state.openTabs.find(t => t.id === tid)
+  if (!tab) {return}
+
+  const streamState = tabStreamState.get(tid)
+
+  if (tabMessagesCache.has(tid)) {
+    state.messages = tabMessagesCache.get(tid)
+    state.currentConversationId = tab.conversationId
+  } else if (tab.conversationId) {
+    try {
+      const msgs = await dbGetMessages(tab.conversationId)
+      state.messages = msgs.map(m => ({ ...m, streaming: false }))
+      state.currentConversationId = tab.conversationId
+    } catch (e) {
+      console.error('Failed to load tab conversation:', e)
+      state.messages = []
+      state.currentConversationId = null
+    }
+  } else {
+    state.messages = []
+    state.currentConversationId = null
+  }
+
+  state.streaming = streamState?.streaming || false
+  state.loading = streamState?.loading || false
+  state.abortController = streamState?.abortController || null
+
+  state.historyOpen = false
+  renderTabBar()
+  callbacks.render()
+  callbacks.renderHistoryDropdown()
+  persistTabState()
+}
+
+export function closeTab(tid) {
+  const idx = state.openTabs.findIndex(t => t.id === tid)
+  if (idx === -1) {return}
+
+  const streamState = tabStreamState.get(tid)
+  if (streamState?.abortController) {
+    streamState.abortController.abort()
+    tabStreamState.delete(tid)
+  }
+  tabMessagesCache.delete(tid)
+
+  if (tid === state.activeTabId) {
+    state.streaming = false
+    state.loading = false
+    state.abortController = null
+  }
+
+  state.openTabs.splice(idx, 1)
+
+  if (state.openTabs.length === 0) {
+    createTab(null, 'New Chat')
+    state.messages = []
+    state.currentConversationId = null
+    renderTabBar()
+    callbacks.render()
+    persistTabState()
+    return
+  }
+
+  if (tid === state.activeTabId) {
+    const newIdx = Math.min(idx, state.openTabs.length - 1)
+    switchTab(state.openTabs[newIdx].id)
+  } else {
+    renderTabBar()
+    persistTabState()
+  }
+}
+
+export function newChat() {
+  const existingNew = state.openTabs.find(t => !t.conversationId)
+  if (existingNew && state.activeTabId !== existingNew.id) {
+    switchTab(existingNew.id)
+    return
+  }
+  if (existingNew && state.activeTabId === existingNew.id && state.messages.length === 0) {return}
+
+  if (state.activeTabId) {tabMessagesCache.set(state.activeTabId, state.messages)}
+
+  createTab(null, 'New Chat')
+  state.currentConversationId = null
+  state.messages = []
+  state.streaming = false
+  state.loading = false
+  state.abortController = null
+  state.historyOpen = false
+  renderTabBar()
+  callbacks.render()
+  callbacks.renderHistoryDropdown()
+  persistTabState()
+}
+
+export async function loadConversation(cid) {
+  const existingTab = state.openTabs.find(t => t.conversationId === cid)
+  if (existingTab) {
+    const conv = state.conversations.find(c => c.id === cid)
+    if (conv) {
+      const now = Date.now()
+      const createdAt = Number(conv.createdAt || now)
+      const updatedAt = Number(conv.updatedAt || createdAt)
+      callbacks.trackAnalytics('conversation_resumed', {
+        conversation_id: conv.id,
+        age_since_created_hours: Math.max(0, Math.round((now - createdAt) / 36_000) / 100),
+        age_since_last_message_hours: Math.max(0, Math.round((now - updatedAt) / 36_000) / 100),
+      })
+    }
+    await switchTab(existingTab.id)
+    return
+  }
+
+  if (state.activeTabId) {tabMessagesCache.set(state.activeTabId, state.messages)}
+
+  try {
+    const msgs = await dbGetMessages(cid)
+    state.messages = msgs.map(m => ({ ...m, streaming: false }))
+    state.currentConversationId = cid
+
+    const conv = state.conversations.find(c => c.id === cid)
+    const title = conv ? conv.title : 'Chat'
+    if (conv) {
+      const now = Date.now()
+      const createdAt = Number(conv.createdAt || now)
+      const updatedAt = Number(conv.updatedAt || createdAt)
+      callbacks.trackAnalytics('conversation_resumed', {
+        conversation_id: conv.id,
+        age_since_created_hours: Math.max(0, Math.round((now - createdAt) / 36_000) / 100),
+        age_since_last_message_hours: Math.max(0, Math.round((now - updatedAt) / 36_000) / 100),
+      })
+    }
+
+    const activeTab = state.openTabs.find(t => t.id === state.activeTabId)
+    if (activeTab && !activeTab.conversationId && state.messages.length === 0) {
+      activeTab.conversationId = cid
+      activeTab.title = title
+    } else {
+      createTab(cid, title)
+    }
+
+    state.historyOpen = false
+    renderTabBar()
+    callbacks.render()
+    callbacks.renderHistoryDropdown()
+    persistTabState()
+  } catch (e) {
+    console.error('Failed to load conversation:', e)
+  }
+}
+
+export async function clearAllChats() {
+  state.abortController?.abort()
+  for (const streamState of tabStreamState.values()) {
+    streamState.abortController?.abort()
+  }
+
+  tabStreamState.clear()
+  tabMessagesCache.clear()
+
+  try {
+    await dbClearChatState()
+  } catch (e) {
+    console.error('Failed to clear conversations:', e)
+    return
+  }
+
+  state.conversations = []
+  state.openTabs = []
+  createTab(null, 'New Chat')
+  state.currentConversationId = null
+  state.messages = []
+  state.streaming = false
+  state.loading = false
+  state.abortController = null
+  state.historyOpen = false
+
+  renderTabBar()
+  callbacks.render()
+  callbacks.renderHistoryDropdown()
+  callbacks.syncRecentConversations()
+  persistTabState()
+}
+
+export function confirmClearAllChats() {
+  if (state.conversations.length === 0) {return}
+  showClearChatsConfirmation(() => {
+    clearAllChats()
+  })
+}
+
+let undoTimeout = null
+
+function showUndoToast(message, onUndo) {
+  dismissUndoToast()
+  const toast = document.createElement('div')
+  toast.className = 'undo-toast'
+  toast.innerHTML = `<span>${message}</span><button class="undo-btn">Undo</button>`
+  document.body.appendChild(toast)
+  toast.querySelector('.undo-btn').addEventListener('click', () => {
+    dismissUndoToast()
+    onUndo()
+  })
+  requestAnimationFrame(() => toast.classList.add('visible'))
+  undoTimeout = setTimeout(dismissUndoToast, 5000)
+}
+
+function dismissUndoToast() {
+  clearTimeout(undoTimeout)
+  undoTimeout = null
+  const existing = document.querySelector('.undo-toast')
+  if (existing) {existing.remove()}
+}
+
+export async function deleteConversation(id) {
+  const conv = state.conversations.find(c => c.id === id)
+  const convMessages = conv ? await dbGetMessages(id).catch(() => []) : []
+  const convIndex = state.conversations.indexOf(conv)
+
+  try {
+    await dbDeleteConversation(id)
+    state.conversations = state.conversations.filter(c => c.id !== id)
+
+    const affectedTabs = state.openTabs.filter(t => t.conversationId === id)
+    for (const tab of affectedTabs) {
+      tab.conversationId = null
+      tab.title = 'New Chat'
+    }
+
+    if (state.currentConversationId === id) {
+      state.currentConversationId = null
+      state.messages = []
+      callbacks.render()
+    }
+
+    renderTabBar()
+    callbacks.renderHistoryDropdown()
+    callbacks.syncRecentConversations()
+    persistTabState()
+
+    if (conv) {
+      showUndoToast('Chat deleted', async () => {
+        try {
+          await dbSaveConversation(conv)
+          for (const m of convMessages) {await dbSaveMessage(m)}
+          state.conversations.splice(Math.min(convIndex, state.conversations.length), 0, conv)
+          state.conversations.sort((a, b) => b.updatedAt - a.updatedAt)
+          callbacks.renderHistoryDropdown()
+          callbacks.syncRecentConversations()
+        } catch (e) { console.error('Failed to undo delete:', e) }
+      })
+    }
+  } catch (e) {
+    console.error('Failed to delete conversation:', e)
+  }
+}
+
+// --- Tab bar rendering ---
+
+export function renderTabBar() {
+  const bar = $('#tab-bar')
+  if (!bar) {return}
+
+  const scrollArea = bar.querySelector('.tab-scroll')
+  if (!scrollArea) {return}
+
+  scrollArea.innerHTML = state.openTabs.map(t => `
+    <div class="tab-item ${t.id === state.activeTabId ? 'active' : ''}" data-tab-id="${t.id}" title="${escapeHtml(t.title)}">
+      <span class="tab-title">${escapeHtml(t.title)}</span>
+      <button class="tab-close" data-tab-id="${t.id}" title="Close">
+        <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+      </button>
+    </div>
+  `).join('')
+
+  scrollArea.querySelectorAll('.tab-item').forEach(el => {
+    el.addEventListener('click', (e) => {
+      if (e.target.closest('.tab-close')) {return}
+      switchTab(el.dataset.tabId)
+    })
+  })
+
+  scrollArea.querySelectorAll('.tab-close').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation()
+      closeTab(btn.dataset.tabId)
+    })
+  })
+}
diff --git a/src/webview/client/docs-ai/webview.ts b/src/webview/client/docs-ai/webview.ts
new file mode 100644
index 0000000..fdf52fd
--- /dev/null
+++ b/src/webview/client/docs-ai/webview.ts
@@ -0,0 +1,1035 @@
+// @ts-nocheck
+
+import { renderMarkdown } from "./markdown"
+import { dbGetMessages, dbSaveConversation, dbSaveMessage, dbDeleteMessagesAfter, dbGetAllConversations, dbLoadTabState } from "./db"
+import {
+  API_BASE, API_URL, vscode, state, tabMessagesCache, tabStreamState,
+  $, conversationEl, inputEl, scrollToBottom, normalizeSources,
+  getSourceUrl, getSourceLabel, escapeHtml, pickStarters,
+  uid, convId, timeAgo, callbacks, IDE_PLATFORM, INITIAL_PROMPT, INITIAL_CONVERSATION_ID,
+} from "./state"
+import {
+  persistMessage, updateConversationTimestamp, persistTabState, loadConversations,
+  createTab, switchTab, closeTab, newChat, loadConversation, deleteConversation,
+  renderTabBar, enforceConversationLimit,
+} from "./tabs"
+import { toggleHistoryDropdown, renderHistoryDropdown } from "./history"
+import { initActionToolbar } from "../actionToolbar"
+
+// Wire up callbacks so tabs.js and history.js can call render/renderHistoryDropdown without circular imports
+callbacks.render = render
+callbacks.renderHistoryDropdown = renderHistoryDropdown
+callbacks.syncRecentConversations = syncRecentConversations
+callbacks.trackAnalytics = trackAnalytics
+
+function syncRecentConversations() {
+  vscode.postMessage({
+    command: 'docsAiRecentConversations',
+    conversations: state.conversations.map(c => ({
+      id: c.id,
+      title: c.title,
+      createdAt: c.createdAt,
+      updatedAt: c.updatedAt,
+    })),
+  })
+}
+
+function trackAnalytics(eventName, payload = {}) {
+  vscode.postMessage({
+    command: 'analyticsEvent',
+    eventName,
+    payload,
+  })
+}
+
+function trackConversationResumed(conv, entryPoint) {
+  if (!conv) {return}
+  const now = Date.now()
+  const createdAt = Number(conv.createdAt || now)
+  const updatedAt = Number(conv.updatedAt || createdAt)
+  trackAnalytics('conversation_resumed', {
+    conversation_id: conv.id,
+    age_since_created_hours: Math.max(0, Math.round((now - createdAt) / 36_000) / 100),
+    age_since_last_message_hours: Math.max(0, Math.round((now - updatedAt) / 36_000) / 100),
+  })
+}
+
+async function syncRecentConversationsFromStorage() {
+  await loadConversations()
+  syncRecentConversations()
+}
+
+// --- Feedback helpers ---
+
+function updateFeedbackButtons(actions, msg) {
+  if (!actions) {return}
+  const upBtn = actions.querySelector('.msg-feedback-up')
+  const downBtn = actions.querySelector('.msg-feedback-down')
+  if (upBtn) {
+    upBtn.classList.toggle('selected', msg.feedback === 'up')
+    upBtn.querySelector('svg').setAttribute('fill', msg.feedback === 'up' ? 'currentColor' : 'none')
+  }
+  if (downBtn) {
+    downBtn.classList.toggle('selected', msg.feedback === 'down')
+    downBtn.querySelector('svg').setAttribute('fill', msg.feedback === 'down' ? 'currentColor' : 'none')
+  }
+}
+
+function sendFeedbackToApi(msg, rating, starRating, comment) {
+  const idx = state.messages.indexOf(msg)
+  const userMsg = [...state.messages.slice(0, idx)].reverse().find(m => m.role === 'user')
+  const body = {
+    messageId: msg.id,
+    conversationId: msg.conversationId || state.currentConversationId,
+    platform: IDE_PLATFORM,
+    rating,
+    messageContent: msg.content || '',
+    userMessage: userMsg?.content || '',
+  }
+  if (starRating) {body.starRating = starRating}
+  if (comment) {body.comment = comment}
+  fetch(`${API_BASE}/api/feedback`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  }).catch(err => console.error('Feedback send failed:', err))
+}
+
+function closeFeedbackForm(article) {
+  const existing = article?.querySelector('.feedback-form')
+  if (existing) {existing.remove()}
+}
+
+function showFeedbackForm(article, msg) {
+  closeFeedbackForm(article)
+  const form = document.createElement('div')
+  form.className = 'feedback-form'
+  let selectedStar = 0
+
+  form.innerHTML = `
+    <div class="feedback-form-inner">
+      <div class="feedback-form-header">What went wrong?</div>
+      <div class="feedback-stars" role="group" aria-label="Rating">
+        ${[1,2,3,4,5].map(n => `<button class="feedback-star" data-star="${n}" title="${n} star${n > 1 ? 's' : ''}">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/></svg>
+        </button>`).join('')}
+      </div>
+      <textarea class="feedback-comment" placeholder="Tell us more (optional)..." rows="3"></textarea>
+      <div class="feedback-form-actions">
+        <button class="feedback-cancel-btn">Cancel</button>
+        <button class="feedback-submit-btn">Submit</button>
+      </div>
+    </div>`
+
+  const actionsEl = article.querySelector('.msg-actions')
+  if (actionsEl) {actionsEl.after(form)}
+  else {article.appendChild(form)}
+
+  requestAnimationFrame(() => form.scrollIntoView({ behavior: 'smooth', block: 'nearest' }))
+
+  const stars = form.querySelectorAll('.feedback-star')
+  const updateStars = () => {
+    stars.forEach(s => {
+      const v = parseInt(s.dataset.star)
+      const svg = s.querySelector('svg')
+      s.classList.toggle('active', v <= selectedStar)
+      svg.setAttribute('fill', v <= selectedStar ? 'currentColor' : 'none')
+    })
+  }
+
+  stars.forEach(s => {
+    s.addEventListener('click', () => {
+      selectedStar = parseInt(s.dataset.star)
+      updateStars()
+    })
+  })
+
+  form.querySelector('.feedback-cancel-btn').addEventListener('click', () => {
+    msg.feedback = null
+    persistMessage(msg)
+    updateFeedbackButtons(article.querySelector('.msg-actions'), msg)
+    form.remove()
+  })
+
+  form.querySelector('.feedback-submit-btn').addEventListener('click', () => {
+    const comment = form.querySelector('.feedback-comment').value.trim()
+    sendFeedbackToApi(msg, 'down', selectedStar || undefined, comment || undefined)
+    trackAnalytics('conversation_rated', {
+      rating: 'down',
+      star_rating: selectedStar || undefined,
+      has_comment: !!comment,
+      conversation_id: msg.conversationId || state.currentConversationId,
+    })
+
+    const inner = form.querySelector('.feedback-form-inner')
+    inner.innerHTML = `
+      <div class="feedback-thankyou">
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6L9 17l-5-5"/></svg>
+        <span>Thanks for your feedback</span>
+      </div>`
+    setTimeout(() => {
+      form.style.opacity = '0'
+      form.style.transition = 'opacity 0.2s'
+      setTimeout(() => form.remove(), 200)
+    }, 1500)
+  })
+}
+
+// --- Render ---
+
+function render() {
+  const conv = conversationEl()
+  if (!conv) {return}
+
+  if (state.messages.length === 0) {
+    conv.classList.add('empty-state')
+    const starters = pickStarters(3)
+    const recentConvs = state.conversations.slice(0, 3)
+    const recentHtml = recentConvs.length > 0 ? `
+      <div class="recent-chats">
+        <div class="recent-heading">Recent conversations</div>
+        ${recentConvs.map(c => `
+          <button class="recent-item" data-conv-id="${c.id}">
+            <svg class="recent-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
+            <span class="recent-title">${escapeHtml(c.title)}</span>
+            <span class="recent-time">${timeAgo(c.updatedAt || c.createdAt)}</span>
+          </button>
+        `).join('')}
+      </div>` : ''
+
+    conv.innerHTML = `
+      <div class="empty">
+        <div class="empty-heading">Ask Cloudinary AI</div>
+        <p class="empty-sub">Ask me anything about our products and documentation.</p>
+        <div class="empty-input-row">
+          <textarea id="empty-input" class="empty-input" rows="1" placeholder="Send a message..." autocomplete="off" dir="auto"></textarea>
+          <button id="empty-send-btn" class="empty-send-btn" disabled title="Send message">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+          </button>
+        </div>
+        <div class="chips">
+          ${starters.map(q => `<button class="chip" data-question="${q.replace(/"/g, '&quot;')}">${q}</button>`).join('')}
+        </div>
+      </div>
+      ${recentHtml}`
+
+    const emptyInput = conv.querySelector('#empty-input')
+    const emptySendBtn = conv.querySelector('#empty-send-btn')
+
+    if (emptyInput) {
+      emptyInput.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault()
+          ask(emptyInput.value)
+        }
+      })
+      emptyInput.addEventListener('input', () => {
+        emptyInput.style.height = 'auto'
+        emptyInput.style.height = Math.min(emptyInput.scrollHeight, 150) + 'px'
+        if (emptySendBtn) {emptySendBtn.disabled = !emptyInput.value.trim()}
+      })
+    }
+    if (emptySendBtn) {
+      emptySendBtn.addEventListener('click', () => {
+        if (emptyInput) {ask(emptyInput.value)}
+      })
+    }
+
+    conv.querySelectorAll('.chip').forEach(btn => {
+      btn.addEventListener('click', () => ask(btn.dataset.question))
+    })
+    conv.querySelectorAll('.recent-item').forEach(btn => {
+      btn.addEventListener('click', () => loadConversation(btn.dataset.convId))
+    })
+    updateComposer()
+    if (emptyInput) {queueMicrotask(() => emptyInput.focus())}
+    return
+  }
+
+  conv.classList.remove('empty-state')
+
+  const lastAssistantId = [...state.messages].reverse().find(m => m.role === 'assistant')?.id
+
+  conv.innerHTML = state.messages.map(m => {
+    let bubbleContent = ''
+    if (m.role === 'assistant') {
+      if (m.content) {
+        bubbleContent = `<div class="md" dir="auto">${renderMarkdown(m.content, m.sources || [])}</div>`
+      } else {
+        bubbleContent = '<p class="muted">Thinking...</p>'
+      }
+      if (m.streaming) {bubbleContent += '<span class="cursor">|</span>'}
+    } else {
+      bubbleContent = `<p dir="auto">${escapeHtml(m.content)}</p>`
+    }
+
+    let sourcesHtml = ''
+    if (m.role === 'assistant' && m.sources && m.sources.length) {
+      sourcesHtml = `
+        <div class="sources">
+          <button class="sources-toggle" data-id="${m.id}">
+            <span>Sources</span>
+            <span class="chevron ${m.sourcesOpen ? 'chevron-open' : ''}"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg></span>
+          </button>
+          ${m.sourcesOpen ? `<div class="sources-list">${m.sources.map((s, index) =>
+            `<a href="${escapeHtml(getSourceUrl(s))}" target="_blank" rel="noopener noreferrer" class="source-item">
+              <span class="source-index">${index + 1}</span>
+              <span class="source-title">${escapeHtml(getSourceLabel(s))}</span>
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>
+            </a>`).join('')}</div>` : ''}
+        </div>`
+    }
+
+    let followUpsHtml = ''
+    if (m.role === 'assistant' && m.followUpQuestions && m.followUpQuestions.length && !m.streaming && m.id === lastAssistantId) {
+      followUpsHtml = `
+        <div class="follow-ups">
+          ${m.followUpQuestions.map(q => {
+            const question = escapeHtml(q)
+            return `<button class="follow-up-btn" dir="auto" data-question="${question}">${question}</button>`
+          }
+          ).join('')}
+        </div>`
+    }
+
+    const feedbackBtns = (!m.streaming && m.role === 'assistant') ? `<span class="msg-actions-group"><button class="msg-feedback msg-feedback-up${m.feedback === 'up' ? ' selected' : ''}" data-msg-id="${m.id}" title="Good response"><svg width="14" height="14" viewBox="0 0 24 24" fill="${m.feedback === 'up' ? 'currentColor' : 'none'}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3"/></svg></button><button class="msg-feedback msg-feedback-down${m.feedback === 'down' ? ' selected' : ''}" data-msg-id="${m.id}" title="Bad response"><svg width="14" height="14" viewBox="0 0 24 24" fill="${m.feedback === 'down' ? 'currentColor' : 'none'}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 15v4a3 3 0 0 0 3 3l4-9V2H5.72a2 2 0 0 0-2 1.7l-1.38 9a2 2 0 0 0 2 2.3zm7-13h2.67A2.31 2.31 0 0 1 22 4v7a2.31 2.31 0 0 1-2.33 2H17"/></svg></button></span><span class="msg-actions-sep"></span>` : ''
+    const copyBtn = !m.streaming ? `<div class="msg-actions">${feedbackBtns}<button class="msg-copy" data-msg-id="${m.id}" title="Copy message"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button></div>` : ''
+
+    return `
+      <article class="message ${m.role === 'user' ? 'user-message' : ''}">
+        <div class="message-meta ${m.role === 'assistant' ? 'right' : ''}"><span class="role-label">${m.role === 'user' ? 'You' : 'Cloudinary AI'}</span></div>
+        <div class="bubble ${m.role} ${m.error ? 'error' : ''}" dir="auto">${bubbleContent}</div>
+        ${copyBtn}
+        ${sourcesHtml}
+        ${followUpsHtml}
+      </article>`
+  }).join('')
+
+  conv.querySelectorAll('.sources-toggle').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const id = btn.dataset.id
+      const msg = state.messages.find(m => m.id === id)
+      if (msg) {
+        msg.sourcesOpen = !msg.sourcesOpen
+        render()
+        persistMessage(msg)
+      }
+    })
+  })
+  conv.querySelectorAll('.follow-up-btn').forEach(btn => {
+    btn.addEventListener('click', () => ask(btn.dataset.question))
+  })
+
+  conv.querySelectorAll('.code-copy').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const code = btn.dataset.code || ''
+      try {
+        navigator.clipboard.writeText(code)
+      } catch (_) {
+        const ta = document.createElement('textarea')
+        ta.value = code
+        ta.style.position = 'fixed'
+        ta.style.opacity = '0'
+        document.body.appendChild(ta)
+        ta.select()
+        document.execCommand('copy')
+        document.body.removeChild(ta)
+      }
+      const label = btn.querySelector('span')
+      if (label) {
+        const orig = label.textContent
+        label.textContent = 'Copied!'
+        btn.classList.add('copied')
+        setTimeout(() => { label.textContent = orig; btn.classList.remove('copied') }, 1500)
+      }
+      trackAnalytics('copy_message', {
+        copy_type: 'code',
+        code_length: code.length,
+        conversation_id: state.currentConversationId,
+      })
+    })
+  })
+
+  conv.querySelectorAll('.msg-copy').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const msg = state.messages.find(m => m.id === btn.dataset.msgId)
+      if (!msg) {return}
+      const text = msg.content || ''
+      try {
+        navigator.clipboard.writeText(text)
+      } catch (_) {
+        const ta = document.createElement('textarea')
+        ta.value = text
+        ta.style.position = 'fixed'
+        ta.style.opacity = '0'
+        document.body.appendChild(ta)
+        ta.select()
+        document.execCommand('copy')
+        document.body.removeChild(ta)
+      }
+      btn.classList.add('copied')
+      btn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6L9 17l-5-5"/></svg>'
+      setTimeout(() => {
+        btn.classList.remove('copied')
+        btn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>'
+      }, 1500)
+      trackAnalytics('copy_message', {
+        copy_type: 'message',
+        copied_role: msg.role,
+        copied_length: text.length,
+        conversation_id: msg.conversationId || state.currentConversationId,
+      })
+    })
+  })
+
+  conv.querySelectorAll('.msg-feedback').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const msgId = btn.dataset.msgId
+      const msg = state.messages.find(m => m.id === msgId)
+      if (!msg) {return}
+      const isUp = btn.classList.contains('msg-feedback-up')
+      const article = btn.closest('.message')
+
+      if (isUp) {
+        const wasSelected = msg.feedback === 'up'
+        msg.feedback = wasSelected ? null : 'up'
+        persistMessage(msg)
+        updateFeedbackButtons(btn.closest('.msg-actions'), msg)
+        closeFeedbackForm(article)
+        sendFeedbackToApi(msg, wasSelected ? 'none' : 'up')
+        if (!wasSelected) {
+          trackAnalytics('conversation_rated', {
+            rating: 'up',
+            conversation_id: msg.conversationId || state.currentConversationId,
+          })
+        }
+        return
+      }
+
+      if (article.querySelector('.feedback-form')) {
+        msg.feedback = null
+        persistMessage(msg)
+        updateFeedbackButtons(btn.closest('.msg-actions'), msg)
+        closeFeedbackForm(article)
+        return
+      }
+      msg.feedback = 'down'
+      persistMessage(msg)
+      updateFeedbackButtons(btn.closest('.msg-actions'), msg)
+      showFeedbackForm(article, msg)
+    })
+  })
+
+  conv.querySelectorAll('.bubble.user').forEach(bubble => {
+    bubble.addEventListener('click', () => {
+      if (bubble.querySelector('.edit-textarea')) {return}
+      const article = bubble.closest('.message')
+      const msgId = article.querySelector('.msg-copy')?.dataset.msgId
+      const msg = state.messages.find(m => m.id === msgId)
+      if (!msg || msg.streaming) {return}
+      const actions = article.querySelector('.msg-actions')
+      if (actions) {actions.style.display = 'none'}
+      const originalHtml = bubble.innerHTML
+      bubble.classList.add('editing')
+      bubble.innerHTML = `
+        <div class="edit-input-row">
+          <textarea class="edit-textarea" dir="auto">${escapeHtml(msg.content)}</textarea>
+          <button class="edit-send-btn" title="Save & Submit">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+          </button>
+        </div>`
+      const textarea = bubble.querySelector('.edit-textarea')
+      const sendBtn = bubble.querySelector('.edit-send-btn')
+      textarea.style.height = textarea.scrollHeight + 'px'
+      textarea.focus()
+      textarea.setSelectionRange(textarea.value.length, textarea.value.length)
+
+      const restoreBubble = () => {
+        bubble.classList.remove('editing')
+        bubble.innerHTML = originalHtml
+        if (actions) {actions.style.display = ''}
+      }
+
+      textarea.addEventListener('input', () => {
+        textarea.style.height = 'auto'
+        textarea.style.height = textarea.scrollHeight + 'px'
+        sendBtn.disabled = !textarea.value.trim()
+      })
+      textarea.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault()
+          const newContent = textarea.value.trim()
+          if (newContent) {editMessage(msg.id, newContent)}
+        } else if (e.key === 'Escape') {
+          e.preventDefault()
+          restoreBubble()
+        }
+      })
+      sendBtn.addEventListener('mousedown', (e) => e.preventDefault())
+      sendBtn.addEventListener('click', () => {
+        const newContent = textarea.value.trim()
+        if (newContent) {editMessage(msg.id, newContent)}
+      })
+      textarea.addEventListener('blur', () => restoreBubble())
+    })
+  })
+
+  updateComposer()
+  if (state.shouldAutoScroll) {queueMicrotask(scrollToBottom)}
+  queueMicrotask(() => { const input = inputEl(); if (input) {input.focus()} })
+}
+
+function updateComposer() {
+  const composer = $('.composer')
+  const isEmpty = state.messages.length === 0
+
+  if (composer) {composer.style.display = isEmpty ? 'none' : ''}
+
+  if (isEmpty) {return}
+
+  const sendBtn = $('#send-btn')
+  const stopBtn = $('#stop-btn')
+  const disclaimer = $('#disclaimer')
+  const input = inputEl()
+
+  if (sendBtn && stopBtn) {
+    sendBtn.style.display = state.streaming ? 'none' : 'flex'
+    stopBtn.style.display = state.streaming ? 'flex' : 'none'
+    sendBtn.disabled = state.loading || !(input && input.value.trim())
+  }
+  if (disclaimer) {disclaimer.style.display = ''}
+  if (input) {input.placeholder = state.streaming ? 'Type your next message...' : 'Send a message...'}
+}
+
+function handleStreamEvent(data, askMessages, assistantId, askTabId) {
+  const msg = askMessages.find(m => m.id === assistantId)
+  if (!msg) {return false}
+
+  if (data.type === 'sources') {
+    msg.sources = normalizeSources(data.sources)
+  } else if (data.type === 'chunk') {
+    msg.content = data.fullContent ?? data.content ?? ''
+    msg.streaming = true
+  } else if (data.type === 'done') {
+    msg.content = data.answer ?? msg.content
+    msg.streaming = false
+    if (state.activeTabId === askTabId) {state.streaming = false}
+  } else if (data.type === 'followup') {
+    msg.followUpQuestions = Array.isArray(data.questions) ? data.questions : []
+  } else if (data.type === 'error') {
+    msg.content = data.error ?? 'Error from server'
+    msg.streaming = false
+    msg.error = true
+    if (state.activeTabId === askTabId) {state.streaming = false}
+  } else {
+    return false
+  }
+
+  return true
+}
+
+function processStreamLine(line, askMessages, assistantId, askTabId) {
+  const eventLine = line.trim()
+  if (!eventLine.startsWith('data:')) {return}
+  const json = eventLine.slice(5).trim()
+  if (!json) {return}
+
+  try {
+    const data = JSON.parse(json)
+    if (handleStreamEvent(data, askMessages, assistantId, askTabId) && state.activeTabId === askTabId) {
+      render()
+    }
+  } catch (_) {}
+}
+
+function flushStreamBuffer(buffer, askMessages, assistantId, askTabId) {
+  const pending = buffer.trim()
+  if (!pending) {return}
+  processStreamLine(pending, askMessages, assistantId, askTabId)
+}
+
+// --- Actions ---
+
+async function ask(text) {
+  const prompt = (text || inputEl()?.value || '').trim()
+  if (!prompt) {return}
+  const input = inputEl()
+  if (input) {
+    input.value = ''
+    input.style.height = 'auto'
+  }
+
+  const askTabId = state.activeTabId
+  const wasNewConversation = !state.currentConversationId
+
+  if (!state.currentConversationId) {
+    const id = convId()
+    const title = prompt.length > 50 ? prompt.slice(0, 50) + '...' : prompt
+    const conv = { id, title, createdAt: Date.now(), updatedAt: Date.now() }
+    state.currentConversationId = id
+    state.conversations.unshift(conv)
+    try { await dbSaveConversation(conv) } catch (e) { console.error('Failed to create conversation:', e) }
+    enforceConversationLimit()
+    syncRecentConversations()
+
+    const activeTab = state.openTabs.find(t => t.id === askTabId)
+    if (activeTab) {
+      activeTab.conversationId = id
+      activeTab.title = title
+      renderTabBar()
+      persistTabState()
+    }
+  }
+
+  const askConversationId = state.currentConversationId
+  const askMessages = state.messages
+  const language = navigator.language || ''
+
+  if (wasNewConversation) {
+    trackAnalytics('chat_started', {
+      conversation_id: askConversationId,
+      language,
+    })
+  }
+  trackAnalytics('message_sent', {
+    conversation_id: askConversationId,
+    language,
+    message_length: prompt.length,
+    is_first_message: wasNewConversation,
+  })
+
+  const userMsg = { id: uid(), role: 'user', content: prompt, conversationId: askConversationId, createdAt: Date.now() }
+  const assistantId = uid()
+  const assistantMsg = { id: assistantId, role: 'assistant', content: '', streaming: true, sources: [], followUpQuestions: [], conversationId: askConversationId, createdAt: Date.now() + 1 }
+
+  askMessages.push(userMsg, assistantMsg)
+  tabMessagesCache.set(askTabId, askMessages)
+  state.shouldAutoScroll = true
+  state.loading = true
+  state.streaming = true
+  render()
+
+  try {
+    await dbSaveMessage({ ...userMsg, streaming: false })
+  } catch (e) {
+    console.error('Failed to persist user message:', e)
+  }
+
+  const askAbortController = new AbortController()
+  state.abortController = askAbortController
+  tabStreamState.set(askTabId, { streaming: true, loading: true, abortController: askAbortController })
+
+  try {
+    const historyForRequest = askMessages.filter(m => !m.streaming || m.id === assistantId).map(m => ({ role: m.role, content: m.content }))
+    historyForRequest.pop()
+
+    const res = await fetch(API_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ messages: historyForRequest, conversationId: state.currentConversationId || '', platform: IDE_PLATFORM }),
+      signal: askAbortController.signal,
+    })
+
+    if (!res.ok) {throw new Error(`HTTP ${res.status}`)}
+
+    const reader = res.body.getReader()
+    const dec = new TextDecoder()
+    let buffer = ''
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {break}
+      buffer += dec.decode(value, { stream: true })
+      const lines = buffer.split('\n\n')
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        processStreamLine(line, askMessages, assistantId, askTabId)
+      }
+    }
+    flushStreamBuffer(buffer, askMessages, assistantId, askTabId)
+  } catch (e) {
+    if (e.name !== 'AbortError') {
+      const msg = askMessages.find(m => m.id === assistantId)
+      if (msg) {
+        msg.content = 'Request failed. Please try again.'
+        msg.streaming = false
+        msg.error = true
+      }
+    }
+  } finally {
+    tabStreamState.delete(askTabId)
+
+    const msg = askMessages.find(m => m.id === assistantId)
+    if (msg) {msg.streaming = false}
+
+    if (state.activeTabId === askTabId) {
+      state.abortController = null
+      state.loading = false
+      state.streaming = false
+      render()
+    }
+
+    const conv = state.conversations.find(c => c.id === askConversationId)
+    if (msg && conv) {
+      try {
+        await dbSaveMessage({ ...msg, conversationId: askConversationId, streaming: false })
+      } catch (e) {
+        console.error('Failed to persist assistant message:', e)
+      }
+    }
+
+    if (conv) {
+      conv.updatedAt = Date.now()
+      try { await dbSaveConversation(conv) } catch (e) { console.error('Failed to update conversation:', e) }
+      syncRecentConversations()
+    }
+  }
+}
+
+async function editMessage(msgId, newContent) {
+  const idx = state.messages.findIndex(m => m.id === msgId)
+  if (idx === -1) {return}
+  const msg = state.messages[idx]
+  msg.content = newContent
+
+  state.messages.splice(idx + 1)
+  tabMessagesCache.set(state.activeTabId, state.messages)
+
+  try {
+    await dbSaveMessage({ ...msg, streaming: false })
+    await dbDeleteMessagesAfter(msg.conversationId, msg.createdAt)
+  } catch (e) {
+    console.error('Failed to persist edit:', e)
+  }
+
+  render()
+  await askFromEdit(newContent)
+}
+
+async function askFromEdit(text) {
+  const askTabId = state.activeTabId
+  const askConversationId = state.currentConversationId
+  const askMessages = state.messages
+
+  const assistantId = uid()
+  const assistantMsg = { id: assistantId, role: 'assistant', content: '', streaming: true, sources: [], followUpQuestions: [], conversationId: askConversationId, createdAt: Date.now() + 1 }
+
+  askMessages.push(assistantMsg)
+  tabMessagesCache.set(askTabId, askMessages)
+  state.shouldAutoScroll = true
+  state.loading = true
+  state.streaming = true
+  render()
+
+  const askAbortController = new AbortController()
+  state.abortController = askAbortController
+  tabStreamState.set(askTabId, { streaming: true, loading: true, abortController: askAbortController })
+
+  try {
+    const historyForRequest = askMessages.filter(m => !m.streaming || m.id === assistantId).map(m => ({ role: m.role, content: m.content }))
+    historyForRequest.pop()
+
+    const res = await fetch(API_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ messages: historyForRequest, conversationId: state.currentConversationId || '', platform: IDE_PLATFORM }),
+      signal: askAbortController.signal,
+    })
+
+    if (!res.ok) {throw new Error(`HTTP ${res.status}`)}
+
+    const reader = res.body.getReader()
+    const dec = new TextDecoder()
+    let buffer = ''
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {break}
+      buffer += dec.decode(value, { stream: true })
+      const lines = buffer.split('\n\n')
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        processStreamLine(line, askMessages, assistantId, askTabId)
+      }
+    }
+    flushStreamBuffer(buffer, askMessages, assistantId, askTabId)
+  } catch (e) {
+    if (e.name !== 'AbortError') {
+      const msg = askMessages.find(m => m.id === assistantId)
+      if (msg) {
+        msg.content = 'Request failed. Please try again.'
+        msg.streaming = false
+        msg.error = true
+      }
+    }
+  } finally {
+    tabStreamState.delete(askTabId)
+    const msg = askMessages.find(m => m.id === assistantId)
+    if (msg) {msg.streaming = false}
+    if (state.activeTabId === askTabId) {
+      state.abortController = null
+      state.loading = false
+      state.streaming = false
+      render()
+    }
+    const conv = state.conversations.find(c => c.id === askConversationId)
+    if (msg && conv) {
+      try {
+        await dbSaveMessage({ ...msg, conversationId: askConversationId, streaming: false })
+      } catch (e) {
+        console.error('Failed to persist assistant message:', e)
+      }
+    }
+    if (conv) {
+      conv.updatedAt = Date.now()
+      try { await dbSaveConversation(conv) } catch (e) { console.error('Failed to update conversation:', e) }
+      syncRecentConversations()
+    }
+  }
+}
+
+function stopGeneration() {
+  const streamState = tabStreamState.get(state.activeTabId)
+  const ctrl = streamState?.abortController || state.abortController
+  if (ctrl) {
+    ctrl.abort()
+    tabStreamState.delete(state.activeTabId)
+    state.abortController = null
+    state.streaming = false
+    state.loading = false
+    const last = [...state.messages].reverse().find(m => m.role === 'assistant')
+    if (last && last.streaming) {
+      last.streaming = false
+      last.content = last.content || 'Generation stopped.'
+      persistMessage(last)
+    }
+    render()
+    updateConversationTimestamp()
+  }
+}
+
+async function askFromHomePrompt(text) {
+  const prompt = (text || '').trim()
+  if (!prompt) {return}
+
+  if (state.streaming) {stopGeneration()}
+
+  const activeTab = state.openTabs.find(t => t.id === state.activeTabId)
+  const canUseActiveTab = activeTab && !activeTab.conversationId && state.messages.length === 0
+
+  if (!canUseActiveTab) {
+    if (state.activeTabId) {tabMessagesCache.set(state.activeTabId, state.messages)}
+    createTab(null, 'New Chat')
+    state.currentConversationId = null
+    state.messages = []
+    state.streaming = false
+    state.loading = false
+    state.abortController = null
+    state.historyOpen = false
+    renderTabBar()
+    render()
+    renderHistoryDropdown()
+    persistTabState()
+  }
+
+  await ask(prompt)
+}
+
+// --- Migration from vscode.getState ---
+
+async function migrateFromVSCodeState() {
+  const vsState = vscode.getState()
+  if (!vsState || !vsState.messages || vsState.messages.length === 0) {return null}
+
+  const existing = await dbGetAllConversations()
+  if (existing.length > 0) {
+    vscode.setState({})
+    return null
+  }
+
+  const id = convId()
+  const firstUser = vsState.messages.find(m => m.role === 'user')
+  const title = firstUser
+    ? (firstUser.content.length > 50 ? firstUser.content.slice(0, 50) + '...' : firstUser.content)
+    : 'Previous chat'
+  const now = Date.now()
+
+  await dbSaveConversation({ id, title, createdAt: now, updatedAt: now })
+
+  for (const m of vsState.messages) {
+    await dbSaveMessage({
+      ...m,
+      conversationId: id,
+      streaming: false,
+      createdAt: m.createdAt || now,
+    })
+  }
+
+  vscode.setState({})
+  return id
+}
+
+async function loadInitialConversation(conversationId) {
+  const id = typeof conversationId === 'string' ? conversationId.trim() : ''
+  if (!id) {return false}
+
+  const conv = state.conversations.find(c => c.id === id)
+  if (!conv) {return false}
+
+  createTab(conv.id, conv.title)
+  state.currentConversationId = conv.id
+  try {
+    const msgs = await dbGetMessages(conv.id)
+    state.messages = msgs.map(m => ({ ...m, streaming: false }))
+  } catch (_) {
+    state.messages = []
+  }
+  trackConversationResumed(conv, 'initial_conversation')
+  persistTabState()
+  return true
+}
+
+async function openConversationFromHost(conversationId) {
+  const id = typeof conversationId === 'string' ? conversationId.trim() : ''
+  if (!id) {return}
+  await loadConversations()
+  await loadConversation(id)
+  syncRecentConversations()
+}
+
+// --- Init ---
+
+async function init() {
+  const initialPrompt = INITIAL_PROMPT
+  const initialConversationId = INITIAL_CONVERSATION_ID
+  const migratedId = await migrateFromVSCodeState()
+  await loadConversations()
+
+  let restoredTabState = null
+  if (!initialPrompt && !initialConversationId) {
+    try { restoredTabState = await dbLoadTabState() } catch (_) {}
+  }
+
+  if (initialPrompt) {
+    createTab(null, 'New Chat')
+    persistTabState()
+  } else if (initialConversationId) {
+    const loaded = await loadInitialConversation(initialConversationId)
+    if (!loaded) {
+      createTab(null, 'New Chat')
+      persistTabState()
+    }
+  } else if (restoredTabState && restoredTabState.openTabs && restoredTabState.openTabs.length > 0) {
+    state.openTabs = restoredTabState.openTabs
+    state.activeTabId = restoredTabState.activeTabId
+
+    const validTabIds = state.openTabs.map(t => t.id)
+    if (!validTabIds.includes(state.activeTabId)) {state.activeTabId = state.openTabs[0].id}
+
+    const activeTab = state.openTabs.find(t => t.id === state.activeTabId)
+    if (activeTab && activeTab.conversationId) {
+      try {
+        const msgs = await dbGetMessages(activeTab.conversationId)
+        state.messages = msgs.map(m => ({ ...m, streaming: false }))
+        state.currentConversationId = activeTab.conversationId
+      } catch (e) {
+        state.messages = []
+        state.currentConversationId = null
+      }
+    }
+  } else if (migratedId) {
+    const conv = state.conversations.find(c => c.id === migratedId)
+    createTab(migratedId, conv ? conv.title : 'Previous chat')
+    try {
+      const msgs = await dbGetMessages(migratedId)
+      state.messages = msgs.map(m => ({ ...m, streaming: false }))
+      state.currentConversationId = migratedId
+    } catch (_) {}
+    persistTabState()
+  } else if (state.conversations.length > 0) {
+    const latest = state.conversations[0]
+    createTab(latest.id, latest.title)
+    try {
+      const msgs = await dbGetMessages(latest.id)
+      state.messages = msgs.map(m => ({ ...m, streaming: false }))
+      state.currentConversationId = latest.id
+    } catch (_) {}
+    persistTabState()
+  } else {
+    createTab(null, 'New Chat')
+    persistTabState()
+  }
+
+  renderTabBar()
+  render()
+  syncRecentConversations()
+
+  const conv = conversationEl()
+  if (conv) {
+    conv.addEventListener('scroll', () => {
+      if (!state.streaming) {return}
+      if (state.isAutoScrolling) {return}
+      const isNearBottom = conv.scrollHeight - conv.scrollTop - conv.clientHeight < 120
+      state.shouldAutoScroll = isNearBottom
+    }, { passive: true })
+  }
+
+  const input = inputEl()
+  if (input) {
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault()
+        if (state.streaming) {stopGeneration()}
+        else {ask()}
+      }
+    })
+    input.addEventListener('input', () => {
+      input.style.height = 'auto'
+      input.style.height = Math.min(input.scrollHeight, 150) + 'px'
+      updateComposer()
+    })
+  }
+
+  $('#send-btn')?.addEventListener('click', () => ask())
+  $('#stop-btn')?.addEventListener('click', stopGeneration)
+  initActionToolbar({
+    onAction: (action) => {
+      if (action === 'showHomescreen') {
+        syncRecentConversations()
+      }
+      vscode.postMessage({ command: 'runToolbar', action })
+    },
+  })
+  $('#new-chat-btn')?.addEventListener('click', newChat)
+  $('#history-btn')?.addEventListener('click', toggleHistoryDropdown)
+
+  window.addEventListener('message', (event) => {
+    const msg = event.data
+    if (msg?.command === 'askPrompt') {
+      askFromHomePrompt(msg.prompt)
+    } else if (msg?.command === 'openConversation') {
+      openConversationFromHost(msg.conversationId)
+    } else if (msg?.command === 'syncRecentConversations') {
+      syncRecentConversationsFromStorage()
+    }
+  })
+
+  document.addEventListener('click', (e) => {
+    if (state.historyOpen) {
+      const dropdown = $('#history-dropdown')
+      const historyBtn = $('#history-btn')
+      if (dropdown && !dropdown.contains(e.target) && historyBtn && !historyBtn.contains(e.target)) {
+        state.historyOpen = false
+        renderHistoryDropdown()
+      }
+    }
+  })
+
+  if (initialPrompt) {
+    askFromHomePrompt(initialPrompt)
+  }
+}
+
+document.addEventListener('DOMContentLoaded', init)
diff --git a/src/webview/client/homescreen.ts b/src/webview/client/homescreen.ts
index faf9999..bac8600 100644
--- a/src/webview/client/homescreen.ts
+++ b/src/webview/client/homescreen.ts
@@ -32,12 +32,24 @@ interface AiToolsDataMessage {
 
 interface HomescreenDataMessage {
   command: "homescreenData";
-  hasConfig: boolean;
+  status: "connected" | "setupNeeded" | "invalidCredentials" | "checking";
   cloudName: string;
   folderMode: string;
   envCount: number;
 }
 
+interface DocsAiRecentConversation {
+  id: string;
+  title: string;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+interface DocsAiRecentConversationsMessage {
+  command: "docsAiRecentConversations";
+  conversations: DocsAiRecentConversation[];
+}
+
 interface AiToolsProgressMessage {
   command: "aiToolsProgress";
   item: string;
@@ -49,13 +61,15 @@ interface AiToolsResultMessage {
   errors: string[];
 }
 
-type InboundMessage = AiToolsDataMessage | AiToolsProgressMessage | AiToolsResultMessage;
+type InboundMessage = AiToolsDataMessage | AiToolsProgressMessage | AiToolsResultMessage | DocsAiRecentConversationsMessage;
 
 // ── Module state ──────────────────────────────────────────────────────────────
 
 let _isOpen = false;
-let _dataFetched = false;
 let _cachedData: Omit<AiToolsDataMessage, "command"> | null = null;
+let _docsAiRecentSource: "none" | "host" | "local" = "none";
+let _docsAiConversations: DocsAiRecentConversation[] = [];
+let _docsAiHistoryExpanded = false;
 
 
 // ── DOM helpers ───────────────────────────────────────────────────────────────
@@ -64,6 +78,59 @@ function el<T extends HTMLElement>(id: string): T {
   return document.getElementById(id) as T;
 }
 
+function showClearChatsConfirmation(onConfirm: () => void | Promise<void>): void {
+  document.querySelector(".docs-ai-confirm-overlay")?.remove();
+
+  const previouslyFocused = document.activeElement instanceof HTMLElement
+    ? document.activeElement
+    : null;
+  const overlay = document.createElement("div");
+  overlay.className = "docs-ai-confirm-overlay";
+  overlay.setAttribute("role", "presentation");
+  overlay.innerHTML = `
+    <div class="docs-ai-confirm-dialog" role="dialog" aria-modal="true" aria-labelledby="docs-ai-confirm-title" aria-describedby="docs-ai-confirm-message">
+      <h2 id="docs-ai-confirm-title" class="docs-ai-confirm-title">Delete all conversations?</h2>
+      <p id="docs-ai-confirm-message" class="docs-ai-confirm-message">This will permanently remove all chat history.</p>
+      <div class="docs-ai-confirm-actions">
+        <button class="docs-ai-confirm-btn docs-ai-confirm-cancel" type="button">Cancel</button>
+        <button class="docs-ai-confirm-btn docs-ai-confirm-delete" type="button">Delete All</button>
+      </div>
+    </div>
+  `;
+
+  const cancelButton = overlay.querySelector<HTMLButtonElement>(".docs-ai-confirm-cancel");
+  const deleteButton = overlay.querySelector<HTMLButtonElement>(".docs-ai-confirm-delete");
+  if (!cancelButton || !deleteButton) { return; }
+
+  function close(): void {
+    document.removeEventListener("keydown", handleKeydown);
+    overlay.remove();
+    previouslyFocused?.focus();
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape") {
+      close();
+    }
+  }
+
+  cancelButton.addEventListener("click", close);
+  deleteButton.addEventListener("click", () => {
+    close();
+    void onConfirm();
+  });
+  overlay.addEventListener("mousedown", (event) => {
+    if (event.target === overlay) {
+      close();
+    }
+  });
+
+  document.body.appendChild(overlay);
+  document.addEventListener("keydown", handleKeydown);
+  requestAnimationFrame(() => overlay.classList.add("is-visible"));
+  cancelButton.focus();
+}
+
 function show(id: string): void {
   el(id)?.classList.remove("hidden");
 }
@@ -80,6 +147,127 @@ function escapeHtml(text: string): string {
     .replace(/"/g, "&quot;");
 }
 
+function timeAgo(timestamp?: number): string {
+  if (!timestamp || !Number.isFinite(timestamp)) {
+    return "";
+  }
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) { return "just now"; }
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) { return `${minutes}m`; }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) { return `${hours}h`; }
+  const days = Math.floor(hours / 24);
+  if (days < 30) { return `${days}d`; }
+  return new Date(timestamp).toLocaleDateString();
+}
+
+function groupDocsAiConversations(conversations: DocsAiRecentConversation[]): { label: string; items: DocsAiRecentConversation[] }[] {
+  const now = new Date();
+  const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  const yesterdayStart = todayStart - 86400000;
+  const weekStart = todayStart - 6 * 86400000;
+
+  const today: DocsAiRecentConversation[] = [];
+  const yesterday: DocsAiRecentConversation[] = [];
+  const week: DocsAiRecentConversation[] = [];
+  const older: DocsAiRecentConversation[] = [];
+
+  conversations.forEach((conversation) => {
+    const timestamp = conversation.updatedAt ?? conversation.createdAt ?? 0;
+    if (timestamp >= todayStart) {
+      today.push(conversation);
+    } else if (timestamp >= yesterdayStart) {
+      yesterday.push(conversation);
+    } else if (timestamp >= weekStart) {
+      week.push(conversation);
+    } else {
+      older.push(conversation);
+    }
+  });
+
+  return [
+    { label: "Today", items: today },
+    { label: "Yesterday", items: yesterday },
+    { label: "Previous 7 days", items: week },
+    { label: "Older", items: older },
+  ].filter((group) => group.items.length > 0);
+}
+
+function openDocsAiDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (!("indexedDB" in window)) {
+      reject(new Error("IndexedDB unavailable"));
+      return;
+    }
+
+    const request = indexedDB.open("CloudinaryVSCodeChatDB", 2);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains("conversations")) {
+        const convStore = db.createObjectStore("conversations", { keyPath: "id" });
+        convStore.createIndex("updatedAt", "updatedAt", { unique: false });
+      }
+      if (!db.objectStoreNames.contains("messages")) {
+        const msgStore = db.createObjectStore("messages", { keyPath: "id" });
+        msgStore.createIndex("conversationId", "conversationId", { unique: false });
+      }
+      if (!db.objectStoreNames.contains("tabState")) {
+        db.createObjectStore("tabState", { keyPath: "id" });
+      }
+    };
+
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+async function loadDocsAiConversations(): Promise<DocsAiRecentConversation[]> {
+  const db = await openDocsAiDb();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction("conversations", "readonly");
+    const request = tx.objectStore("conversations").getAll();
+    request.onsuccess = () => {
+      const conversations = (request.result || []) as DocsAiRecentConversation[];
+      conversations.sort((a, b) => (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0));
+      resolve(conversations);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+
+async function clearDocsAiConversationStores(): Promise<void> {
+  const db = await openDocsAiDb();
+  const stores = ["conversations", "messages", "tabState"].filter((storeName) =>
+    db.objectStoreNames.contains(storeName)
+  );
+  if (stores.length === 0) { return; }
+
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(stores, "readwrite");
+    stores.forEach((storeName) => tx.objectStore(storeName).clear());
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+async function clearDocsAiRecentConversations(): Promise<void> {
+  if (_docsAiConversations.length === 0) { return; }
+
+  showClearChatsConfirmation(async () => {
+    try {
+      await clearDocsAiConversationStores();
+      _docsAiHistoryExpanded = false;
+      _docsAiRecentSource = "local";
+      renderDocsAiRecentConversations([], "local");
+      getVSCode()?.postMessage({ command: "clearDocsAiConversations" });
+    } catch (error) {
+      console.error("Failed to clear Docs AI conversations:", error);
+    }
+  });
+}
+
 // ── State rendering ───────────────────────────────────────────────────────────
 
 function showPanelState(state: "loading" | "ready" | "done" | "error"): void {
@@ -165,8 +353,7 @@ function toggleAccordion(): void {
   btn.setAttribute("aria-expanded", String(_isOpen));
   chevron.classList.toggle("hs-chevron--open", _isOpen);
 
-  if (_isOpen && !_dataFetched) {
-    _dataFetched = true;
+  if (_isOpen && !_cachedData) {
     showPanelState("loading");
     getVSCode()?.postMessage({ command: "aiToolsExpanded" });
   }
@@ -178,9 +365,9 @@ function handleApply(): void {
   if (!_cachedData) { return; }
 
   const skillCheckboxes = document.querySelectorAll<HTMLInputElement>(".hs-ai-cb[data-skill]");
-  const mcpCheckboxes   = document.querySelectorAll<HTMLInputElement>(".hs-ai-cb[data-mcp]");
+  const mcpCheckboxes = document.querySelectorAll<HTMLInputElement>(".hs-ai-cb[data-mcp]");
 
-  const selectedSkills  = [...skillCheckboxes].filter((c) => c.checked && !c.disabled).map((c) => c.dataset.skill!);
+  const selectedSkills = [...skillCheckboxes].filter((c) => c.checked && !c.disabled).map((c) => c.dataset.skill!);
   const selectedMcpKeys = [...mcpCheckboxes].filter((c) => c.checked && !c.disabled).map((c) => c.dataset.mcp!);
 
   document.querySelectorAll<HTMLInputElement>(".hs-ai-cb").forEach((c) => { c.disabled = true; });
@@ -193,8 +380,8 @@ function handleApply(): void {
   getVSCode()?.postMessage({
     command: "installAiTools",
     platform: _cachedData.platform,
-    scope:    _cachedData.scope,
-    skills:   selectedSkills,
+    scope: _cachedData.scope,
+    skills: selectedSkills,
     mcpServers: selectedMcpKeys,
   });
 }
@@ -263,7 +450,6 @@ function handleAiToolsData(msg: AiToolsDataMessage): void {
 }
 
 function handleAiToolsProgress(msg: AiToolsProgressMessage): void {
-  // Find the row by data-skill or data-mcp attribute
   const cb = document.querySelector<HTMLInputElement>(
     `[data-skill="${msg.item}"], [data-mcp="${msg.item}"]`
   );
@@ -272,7 +458,6 @@ function handleAiToolsProgress(msg: AiToolsProgressMessage): void {
   const row = cb.closest(".hs-ai-item");
   if (!row) { return; }
 
-  // Remove existing tick if any
   row.querySelector(".hs-ai-item-tick")?.remove();
 
   const tick = document.createElement("span");
@@ -282,10 +467,12 @@ function handleAiToolsProgress(msg: AiToolsProgressMessage): void {
 }
 
 function handleAiToolsResult(_msg: AiToolsResultMessage): void {
-  _dataFetched = false;
+  // Reload to reflect newly-installed items, but via "aiToolsRefresh" (not
+  // "aiToolsExpanded") so the user's selected platform/scope are preserved
+  // instead of being reset to the auto-detected defaults.
   _cachedData = null;
   showPanelState("loading");
-  getVSCode()?.postMessage({ command: "aiToolsExpanded" });
+  getVSCode()?.postMessage({ command: "aiToolsRefresh" });
 }
 
 // ── Homescreen data ───────────────────────────────────────────────────────────
@@ -296,22 +483,51 @@ function handleHomescreenData(msg: HomescreenDataMessage): void {
   const cloudNameEl = document.getElementById("hs-cloud-name");
   const folderModeEl = document.getElementById("hs-folder-mode");
   const setupBanner = document.getElementById("hs-setup-banner");
+  const setupBannerText = setupBanner?.querySelector<HTMLElement>(".hs-setup-banner-text");
   const searchEl = document.getElementById("hs-search");
   const switchEnvBtn = document.getElementById("hs-btn-switch-env");
   const envCountEl = document.getElementById("hs-env-count");
 
-  statusDot?.classList.toggle("hs-status-dot--warn", !msg.hasConfig);
-  if (statusText) { statusText.textContent = msg.hasConfig ? "Connected" : "Setup needed"; }
+  const connected = msg.status === "connected";
+  const setupNeeded = msg.status === "setupNeeded";
+  const invalidCredentials = msg.status === "invalidCredentials";
+  const checking = msg.status === "checking";
+  const needsAttention = setupNeeded || invalidCredentials;
+
+  // Missing or rejected credentials are alarming. "Checking…" is neutral.
+  statusDot?.classList.toggle("hs-status-dot--warn", needsAttention);
+  if (statusText) {
+    statusText.textContent = connected
+      ? "Connected"
+      : checking
+        ? "Checking…"
+        : invalidCredentials
+          ? "Credentials invalid"
+          : "Setup needed";
+  }
   if (cloudNameEl) {
-    cloudNameEl.textContent = msg.hasConfig ? msg.cloudName : "Not configured";
-    cloudNameEl.classList.toggle("hs-cloud-name--placeholder", !msg.hasConfig);
+    // Show the cloud name whenever one is configured (even while checking or if
+    // rejected); only fall back to the placeholder when nothing is set up.
+    const showName = !!msg.cloudName;
+    cloudNameEl.textContent = showName ? msg.cloudName : "Not configured";
+    cloudNameEl.classList.toggle("hs-cloud-name--placeholder", !showName);
   }
   if (folderModeEl) {
+    // Folder mode is only meaningful once credentials are confirmed valid.
     folderModeEl.textContent = msg.folderMode;
-    folderModeEl.classList.toggle("hidden", !msg.hasConfig);
+    folderModeEl.classList.toggle("hidden", !connected);
   }
-  setupBanner?.classList.toggle("hidden", msg.hasConfig);
-  searchEl?.classList.toggle("hidden", !msg.hasConfig);
+  // Prompt setup only when credentials need attention — not while checking.
+  setupBanner?.classList.toggle("hidden", !needsAttention);
+  if (setupBannerText) {
+    setupBannerText.textContent = invalidCredentials
+      ? "Cloudinary credentials are invalid"
+      : msg.cloudName
+      ? "Update your API credentials to connect"
+      : "Add your API credentials to connect";
+  }
+  // Search needs working credentials; keep it hidden until connected.
+  searchEl?.classList.toggle("hidden", !connected);
   switchEnvBtn?.classList.toggle("hidden", msg.envCount <= 1);
   if (envCountEl) { envCountEl.textContent = String(msg.envCount); }
 }
@@ -322,7 +538,6 @@ function initPlatformDropdown(): void {
   const select = el<HTMLSelectElement>("hs-ai-platform-select");
   if (!select) { return; }
   select.addEventListener("change", () => {
-    // Clear pending checkbox selections on platform switch
     document.querySelectorAll<HTMLInputElement>(".hs-ai-cb:not(:disabled)").forEach((cb) => { cb.checked = false; });
     showPanelState("loading");
     getVSCode()?.postMessage({ command: "changePlatform", platform: select.value });
@@ -343,36 +558,64 @@ function initScopeToggle(): void {
 
 // ── Search ────────────────────────────────────────────────────────────────────
 
+let searchLoadingTimer: ReturnType<typeof window.setTimeout> | null = null;
+
+function setSearchLoading(isLoading: boolean): void {
+  const searchEl = document.getElementById("hs-search");
+  const input = document.getElementById("hs-search-input") as HTMLInputElement | null;
+  const clearBtn = document.getElementById("hs-search-clear") as HTMLButtonElement | null;
+  const loadingEl = document.getElementById("hs-search-loading");
+
+  if (searchLoadingTimer) {
+    window.clearTimeout(searchLoadingTimer);
+    searchLoadingTimer = null;
+  }
+
+  searchEl?.classList.toggle("hs-search--loading", isLoading);
+  searchEl?.setAttribute("aria-busy", String(isLoading));
+  input?.setAttribute("aria-busy", String(isLoading));
+  loadingEl?.classList.toggle("hidden", !isLoading);
+
+  if (clearBtn) {
+    clearBtn.classList.toggle("hidden", isLoading || input?.value.trim() === "");
+  }
+
+  if (isLoading) {
+    searchLoadingTimer = window.setTimeout(() => setSearchLoading(false), 8000);
+  }
+}
+
 function initSearch(): void {
   const input = document.getElementById("hs-search-input") as HTMLInputElement | null;
   const clearBtn = document.getElementById("hs-search-clear") as HTMLButtonElement | null;
 
   if (!input) { return; }
 
-  // Show/hide clear button based on input value
   input.addEventListener("input", () => {
+    setSearchLoading(false);
     if (clearBtn) {
       clearBtn.classList.toggle("hidden", input.value.trim() === "");
     }
   });
 
-  // Submit search on Enter
   input.addEventListener("keydown", (e: KeyboardEvent) => {
     if (e.key === "Enter") {
       const query = input.value.trim();
       if (query) {
+        setSearchLoading(true);
         getVSCode()?.postMessage({ command: "searchAssets", data: query });
       }
     }
     if (e.key === "Escape") {
+      setSearchLoading(false);
       input.value = "";
       clearBtn?.classList.add("hidden");
       getVSCode()?.postMessage({ command: "clearSearch" });
     }
   });
 
-  // Clear search
   clearBtn?.addEventListener("click", () => {
+    setSearchLoading(false);
     input.value = "";
     clearBtn.classList.add("hidden");
     input.focus();
@@ -380,6 +623,232 @@ function initSearch(): void {
   });
 }
 
+// ── Docs AI launcher ──────────────────────────────────────────────────────────
+
+function submitDocsAiQuestion(question?: string): void {
+  const input = document.getElementById("hs-docs-ai-input") as HTMLTextAreaElement | null;
+  const prompt = (question ?? input?.value ?? "").trim();
+  if (!prompt) { return; }
+
+  if (input) {
+    input.value = "";
+    input.style.height = "auto";
+  }
+  updateDocsAiSubmit();
+  getVSCode()?.postMessage({ command: "showDocsAI", data: prompt });
+}
+
+function updateDocsAiSubmit(): void {
+  const input = document.getElementById("hs-docs-ai-input") as HTMLTextAreaElement | null;
+  const submit = document.getElementById("hs-docs-ai-submit") as HTMLButtonElement | null;
+  if (submit) {
+    submit.disabled = !input?.value.trim();
+  }
+}
+
+function renderDocsAiRecentConversations(
+  conversations: DocsAiRecentConversation[],
+  source: "host" | "local" = "local"
+): void {
+  const container = document.getElementById("hs-docs-ai-recent");
+  const list = document.getElementById("hs-docs-ai-recent-list");
+  const historyToggle = document.getElementById("hs-docs-ai-history-toggle") as HTMLButtonElement | null;
+  if (!container || !list) { return; }
+
+  const nextConversations = conversations
+    .filter((conversation) => conversation.id && conversation.title)
+    .sort((a, b) => (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0));
+
+  _docsAiConversations = nextConversations;
+  _docsAiRecentSource = source;
+  if (historyToggle) {
+    const toggleText = _docsAiHistoryExpanded ? "Hide recent conversations" : "View recent conversations";
+    const toggleLabel = historyToggle.querySelector<HTMLElement>(".hs-docs-ai-history-toggle-label");
+    historyToggle.classList.toggle("hidden", _docsAiConversations.length === 0);
+    historyToggle.classList.toggle("is-active", _docsAiHistoryExpanded);
+    historyToggle.setAttribute("aria-expanded", String(_docsAiHistoryExpanded));
+    historyToggle.title = toggleText;
+    historyToggle.setAttribute("aria-label", toggleText);
+    if (toggleLabel) {
+      toggleLabel.textContent = toggleText;
+    }
+  }
+
+  if (_docsAiConversations.length === 0) {
+    _docsAiHistoryExpanded = false;
+    if (historyToggle) {
+      historyToggle.classList.remove("is-active");
+      historyToggle.setAttribute("aria-expanded", "false");
+    }
+    container.classList.add("hidden");
+    list.innerHTML = "";
+    return;
+  }
+
+  const visibleConversations = _docsAiHistoryExpanded ? _docsAiConversations : [];
+
+  container.classList.toggle("hidden", !_docsAiHistoryExpanded);
+
+  const renderRow = (conversation: DocsAiRecentConversation) => {
+    const timestamp = conversation.updatedAt ?? conversation.createdAt;
+    return `<button class="hs-docs-ai-recent-item" type="button" data-conv-id="${escapeHtml(conversation.id)}">
+      <svg class="hs-docs-ai-recent-icon" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
+      <span class="hs-docs-ai-recent-title">${escapeHtml(conversation.title)}</span>
+      <span class="hs-docs-ai-recent-time">${escapeHtml(timeAgo(timestamp))}</span>
+    </button>`;
+  };
+
+  list.classList.toggle("hs-docs-ai-recent-list--expanded", _docsAiHistoryExpanded);
+  if (_docsAiHistoryExpanded) {
+    if (visibleConversations.length === 0) {
+      list.innerHTML = `<div class="hs-docs-ai-history-empty">No previous chats yet</div>`;
+    } else {
+      list.innerHTML = groupDocsAiConversations(visibleConversations).map((group) => `
+        <div class="hs-docs-ai-history-group">
+          <div class="hs-docs-ai-history-group-label">${group.label}</div>
+          ${group.items.map(renderRow).join("")}
+        </div>
+      `).join("") + `
+        <div class="hs-docs-ai-history-footer">
+          <button id="hs-docs-ai-clear-all" class="hs-docs-ai-clear-all" type="button">
+            <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6"/><path d="M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/></svg>
+            <span>Clear all chats</span>
+          </button>
+        </div>
+      `;
+    }
+  } else {
+    list.innerHTML = "";
+  }
+
+  list.querySelectorAll<HTMLButtonElement>(".hs-docs-ai-recent-item").forEach((button) => {
+    button.addEventListener("click", () => {
+      const conversationId = button.dataset.convId;
+      if (conversationId) {
+        getVSCode()?.postMessage({ command: "showDocsAIConversation", data: conversationId });
+      }
+    });
+  });
+
+  list.querySelector<HTMLButtonElement>("#hs-docs-ai-clear-all")?.addEventListener("click", () => {
+    void clearDocsAiRecentConversations();
+  });
+}
+
+async function refreshDocsAiRecentConversations(): Promise<void> {
+  try {
+    const conversations = await loadDocsAiConversations();
+    if (conversations.length === 0 && _docsAiConversations.length > 0) {
+      return;
+    }
+    renderDocsAiRecentConversations(conversations, "local");
+  } catch {
+    // The Docs AI webview also pushes a cached recent list through VS Code.
+  }
+}
+
+function initDocsAiPromptScroller(): void {
+  const scroller = document.querySelector<HTMLElement>(".hs-docs-ai-chips");
+  if (!scroller || scroller.children.length < 2) { return; }
+
+  scroller.addEventListener("click", (event: MouseEvent) => {
+    const target = event.target instanceof Element
+      ? event.target.closest<HTMLButtonElement>(".hs-docs-ai-chip")
+      : null;
+    if (!target || !scroller.contains(target)) { return; }
+    submitDocsAiQuestion(target.dataset.question);
+  });
+
+  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) { return; }
+
+  const originalChips = Array.from(scroller.querySelectorAll<HTMLButtonElement>(".hs-docs-ai-chip"));
+  originalChips.forEach((chip) => {
+    const clone = chip.cloneNode(true) as HTMLButtonElement;
+    clone.tabIndex = -1;
+    clone.setAttribute("aria-hidden", "true");
+    scroller.appendChild(clone);
+  });
+
+  let pauseUntil = 0;
+  const pause = () => {
+    pauseUntil = Date.now() + 8000;
+  };
+
+  ["focusin", "mouseenter", "pointerdown", "wheel"].forEach((eventName) => {
+    scroller.addEventListener(eventName, pause, { passive: true });
+  });
+
+  const interval = window.setInterval(() => {
+    if (!document.body.contains(scroller)) {
+      window.clearInterval(interval);
+      return;
+    }
+    if (Date.now() < pauseUntil) { return; }
+
+    const chips = Array.from(scroller.querySelectorAll<HTMLButtonElement>(".hs-docs-ai-chip"));
+    const originalCount = originalChips.length;
+    if (chips.length <= originalCount) { return; }
+
+    const chipLeft = (chip: HTMLElement) => chip.offsetLeft - scroller.offsetLeft;
+    const nearestIndex = chips.reduce((nearest, chip, index) => {
+      const distance = Math.abs(chipLeft(chip) - scroller.scrollLeft);
+      const nearestDistance = Math.abs(chipLeft(chips[nearest]) - scroller.scrollLeft);
+      return distance < nearestDistance ? index : nearest;
+    }, 0);
+    const normalizedIndex = nearestIndex >= originalCount ? nearestIndex - originalCount : nearestIndex;
+
+    if (nearestIndex >= originalCount) {
+      scroller.scrollTo({ left: chipLeft(chips[normalizedIndex]), behavior: "auto" });
+    }
+
+    const nextIndex = normalizedIndex + 1;
+    scroller.scrollTo({ left: chipLeft(chips[nextIndex]), behavior: "smooth" });
+
+    if (nextIndex >= originalCount) {
+      window.setTimeout(() => {
+        scroller.scrollTo({ left: chipLeft(chips[nextIndex - originalCount]), behavior: "auto" });
+      }, 900);
+    }
+  }, 3200);
+}
+
+function initDocsAiHome(): void {
+  const input = document.getElementById("hs-docs-ai-input") as HTMLTextAreaElement | null;
+  const submit = document.getElementById("hs-docs-ai-submit") as HTMLButtonElement | null;
+
+  input?.addEventListener("input", () => {
+    input.style.height = "auto";
+    input.style.height = `${Math.min(input.scrollHeight, 200)}px`;
+    updateDocsAiSubmit();
+  });
+
+  input?.addEventListener("keydown", (e: KeyboardEvent) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      submitDocsAiQuestion();
+    }
+  });
+
+  submit?.addEventListener("click", () => submitDocsAiQuestion());
+  document.getElementById("hs-docs-ai-history-toggle")?.addEventListener("click", () => {
+    _docsAiHistoryExpanded = !_docsAiHistoryExpanded;
+    if (_docsAiHistoryExpanded) {
+      getVSCode()?.postMessage({ command: "refreshDocsAiRecentConversations" });
+      void refreshDocsAiRecentConversations();
+    }
+    renderDocsAiRecentConversations(_docsAiConversations, _docsAiRecentSource === "none" ? "local" : _docsAiRecentSource);
+  });
+
+  initDocsAiPromptScroller();
+  void refreshDocsAiRecentConversations();
+  window.addEventListener("focus", () => void refreshDocsAiRecentConversations());
+  document.addEventListener("visibilitychange", () => {
+    if (!document.hidden) {
+      void refreshDocsAiRecentConversations();
+    }
+  });
+}
+
 // ── Init ──────────────────────────────────────────────────────────────────────
 
 function init(): void {
@@ -411,6 +880,7 @@ function init(): void {
 
   // Search input
   initSearch();
+  initDocsAiHome();
   initPlatformDropdown();
   initScopeToggle();
 
@@ -438,6 +908,9 @@ function init(): void {
       case "homescreenData":
         handleHomescreenData(msg as HomescreenDataMessage);
         break;
+      case "docsAiRecentConversations":
+        renderDocsAiRecentConversations((msg as DocsAiRecentConversationsMessage).conversations ?? [], "host");
+        break;
       case "aiToolsData":
         handleAiToolsData(msg as AiToolsDataMessage);
         break;
diff --git a/src/webview/client/library.ts b/src/webview/client/library.ts
new file mode 100644
index 0000000..dde0dde
--- /dev/null
+++ b/src/webview/client/library.ts
@@ -0,0 +1,949 @@
+import { getVSCode, initVSCode } from './common';
+import {
+  ClientAsset,
+  ClientFolder,
+  InboundMessage,
+} from './libraryTypes';
+import { assetIcon, folderIcon, menuIcons, rowIcons } from './libraryIcons';
+import { showMenu } from './libraryMenu';
+import { spliceOutRangeAtDepth } from './libraryRowSplice';
+import { VirtualList } from './libraryVirtualList';
+import { initActionToolbar } from './actionToolbar';
+
+type Row =
+  | { kind: 'folder'; folder: ClientFolder; depth: number; expanded: boolean }
+  | { kind: 'asset'; asset: ClientAsset; depth: number }
+  | { kind: 'loading'; depth: number; label?: string }
+  | { kind: 'searchLoading'; query: string; depth: number }
+  | { kind: 'clearSearch'; label: string; depth: number };
+
+const ROW_HEIGHT = 22;
+const SEARCH_DEBOUNCE_MS = 300;
+
+let list: VirtualList<Row>;
+const flat: Row[] = [];
+const childrenByFolder = new Map<string, Row[]>();
+let selectedIdx = -1;
+let searchMode: { query: string } | null = null;
+let pendingSearchQuery: string | null = null;
+let searchDebounceTimer: ReturnType<typeof window.setTimeout> | null = null;
+
+initVSCode();
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function rebuild(): void {
+  list.setItems(flat.slice());
+}
+
+function formatFileSize(bytes: number | undefined): string {
+  if (!bytes || bytes <= 0) {
+    return '';
+  }
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const k = 1024;
+  const i = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(k)));
+  const value = bytes / Math.pow(k, i);
+  const rounded = i === 0 ? Math.round(value) : Number(value.toFixed(1));
+  return `${rounded} ${units[i]}`;
+}
+
+function isAuthenticatedAsset(asset: ClientAsset): boolean {
+  return asset.type === 'authenticated';
+}
+
+function getAssetMeta(asset: ClientAsset): string {
+  const format = asset.format
+    ? asset.format.toUpperCase()
+    : asset.resource_type.toUpperCase();
+  const size = formatFileSize(asset.bytes);
+  const parts = [format];
+  if (size) {
+    parts.push(size);
+  }
+  if (isAuthenticatedAsset(asset)) {
+    parts.unshift('AUTH');
+  }
+  return parts.join(' · ');
+}
+
+
+function getRowKey(row: Row | undefined): string | null {
+  if (!row) {
+    return null;
+  }
+
+  switch (row.kind) {
+    case 'folder':
+      return `folder:${row.folder.path}`;
+    case 'asset':
+      return `asset:${row.asset.public_id}`;
+    case 'clearSearch':
+      return 'clearSearch';
+    case 'loading':
+      return `loading:${row.depth}`;
+    case 'searchLoading':
+      return `searchLoading:${row.query}`;
+    default:
+      return null;
+  }
+}
+
+function findRowIdxByKey(key: string | null): number {
+  if (!key) {
+    return -1;
+  }
+
+  return flat.findIndex((row) => getRowKey(row) === key);
+}
+
+function showEmptyState(message: string, variant: 'welcome' | 'info' = 'info'): void {
+  let empty = document.getElementById('lib-empty') as HTMLDivElement | null;
+  if (!empty) {
+    empty = document.createElement('div');
+    empty.id = 'lib-empty';
+    empty.className = 'lib-empty';
+    const root = document.getElementById('lib-root');
+    if (root?.parentElement) {
+      root.parentElement.insertBefore(empty, root);
+    }
+  }
+  empty.classList.toggle('lib-empty--welcome', variant === 'welcome');
+  if (variant === 'welcome') {
+    empty.innerHTML = `
+      <div class="lib-empty__glyph">${rowIcons.folder()}</div>
+      <p class="lib-empty__title">${escapeHtml(message)}</p>
+      <button class="lib-empty__cta" data-action="openGlobalConfig">Open configuration</button>
+    `;
+    empty.querySelector<HTMLButtonElement>('.lib-empty__cta')?.addEventListener('click', () => {
+      getVSCode()?.postMessage({ command: 'runToolbar', action: 'openGlobalConfig' });
+    });
+  } else {
+    empty.textContent = message;
+  }
+}
+
+function hideEmptyState(): void {
+  document.getElementById('lib-empty')?.remove();
+}
+
+function showError(message: string): void {
+  let banner = document.getElementById('lib-error') as HTMLDivElement | null;
+  if (!banner) {
+    banner = document.createElement('div');
+    banner.id = 'lib-error';
+    banner.className = 'lib-error';
+    banner.setAttribute('role', 'alert');
+    banner.innerHTML =
+      '<span class="lib-error__dot" aria-hidden="true"></span>' +
+      '<span class="lib-error__msg"></span>' +
+      '<button class="lib-error__retry" type="button">Retry</button>';
+    const toolbar = document.getElementById('lib-toolbar');
+    if (toolbar?.parentElement) {
+      toolbar.parentElement.insertBefore(banner, toolbar.nextSibling);
+    }
+    banner.querySelector('.lib-error__retry')?.addEventListener('click', () => {
+      banner?.remove();
+      getVSCode()?.postMessage({ command: 'runToolbar', action: 'refresh' });
+    });
+  }
+
+  const messageEl = banner.querySelector('.lib-error__msg') as HTMLElement | null;
+  if (messageEl) {
+    messageEl.textContent = message;
+  }
+}
+
+function clearError(): void {
+  document.getElementById('lib-error')?.remove();
+}
+
+function snapshotScroll(): { rowKey: string | null; index: number; offsetRatio: number } {
+  const container = document.getElementById('lib-root') as HTMLElement | null;
+  if (!container) {
+    return { rowKey: null, index: 0, offsetRatio: 0 };
+  }
+
+  const rowHeight = ROW_HEIGHT;
+  const topIdx = Math.floor(container.scrollTop / rowHeight);
+  const row = flat[topIdx];
+  const offset = container.scrollTop - topIdx * rowHeight;
+  return {
+    rowKey: getRowKey(row),
+    index: topIdx,
+    offsetRatio: rowHeight > 0 ? offset / rowHeight : 0,
+  };
+}
+
+function restoreScroll(snapshot: { rowKey: string | null; index: number; offsetRatio: number }): void {
+  const container = document.getElementById('lib-root') as HTMLElement | null;
+  if (!container) {
+    return;
+  }
+
+  const rowHeight = ROW_HEIGHT;
+  const idx = findRowIdxByKey(snapshot.rowKey);
+  const targetIdx = idx >= 0
+    ? idx
+    : Math.max(0, Math.min(flat.length - 1, snapshot.index));
+  container.scrollTop = targetIdx * rowHeight + snapshot.offsetRatio * rowHeight;
+}
+
+function setSelected(idx: number): void {
+  selectedIdx = Math.max(-1, Math.min(flat.length - 1, idx));
+  list.render();
+
+  if (selectedIdx < 0) {
+    return;
+  }
+
+  const container = document.getElementById('lib-root') as HTMLElement | null;
+  if (!container) {
+    return;
+  }
+
+  const rowHeight = ROW_HEIGHT;
+  const rowTop = selectedIdx * rowHeight;
+  if (rowTop < container.scrollTop) {
+    container.scrollTop = rowTop;
+  }
+  if (rowTop + rowHeight > container.scrollTop + container.clientHeight) {
+    container.scrollTop = rowTop + rowHeight - container.clientHeight;
+  }
+}
+
+function renderRow(el: HTMLElement, row: Row, index: number): void {
+  el.className = 'lib-row';
+  el.removeAttribute('data-path');
+  el.removeAttribute('data-public-id');
+  el.removeAttribute('role');
+  el.removeAttribute('title');
+
+  if (index === selectedIdx) {
+    el.classList.add('lib-row--selected');
+  }
+
+  const indent = `<span class="lib-indent" style="width:${row.depth * 12}px"></span>`;
+
+  if (row.kind === 'folder') {
+    el.classList.add('lib-row--folder');
+    if (row.expanded) {
+      el.classList.add('lib-row--folder-open');
+    }
+    el.dataset.path = row.folder.path;
+    el.setAttribute('role', 'treeitem');
+    el.setAttribute('aria-expanded', String(row.expanded));
+    const twistieClass = row.expanded ? 'lib-twistie lib-twistie--open' : 'lib-twistie';
+    el.innerHTML = `${indent}<span class="${twistieClass}">${rowIcons.chevron()}</span><span class="lib-icon lib-icon--folder">${folderIcon(row.expanded)}</span><span class="lib-name">${escapeHtml(row.folder.name)}</span>`;
+    return;
+  }
+
+  if (row.kind === 'asset') {
+    el.classList.add('lib-row--asset');
+    el.classList.add(`lib-row--${row.asset.resource_type}`);
+    if (isAuthenticatedAsset(row.asset)) {
+      el.classList.add('lib-row--authenticated');
+    }
+    el.dataset.publicId = row.asset.public_id;
+    el.setAttribute('role', 'treeitem');
+    const name =
+      row.asset.display_name ||
+      row.asset.public_id.split('/').pop() ||
+      row.asset.public_id;
+    const meta = getAssetMeta(row.asset);
+    const authIcon = isAuthenticatedAsset(row.asset)
+      ? `<span class="lib-auth-lock" title="Authenticated delivery" aria-label="Authenticated delivery">${rowIcons.lock()}</span>`
+      : '';
+    el.title = isAuthenticatedAsset(row.asset) ? `${name} · authenticated delivery` : name;
+    el.innerHTML = `${indent}<span class="lib-twistie-spacer"></span><span class="lib-icon lib-icon--asset">${assetIcon(row.asset.resource_type)}</span><span class="lib-name">${escapeHtml(name)}</span>${authIcon}<span class="lib-meta">${escapeHtml(meta)}</span>`;
+    return;
+  }
+
+  if (row.kind === 'clearSearch') {
+    el.classList.add('lib-row--clear');
+    el.innerHTML = `${indent}<span class="lib-clear-chip"><span class="lib-clear-chip__icon">${rowIcons.close()}</span><span class="lib-clear-chip__label">${escapeHtml(row.label)}</span></span>`;
+    return;
+  }
+
+  if (row.kind === 'searchLoading') {
+    el.classList.add('lib-row--loading', 'lib-row--search-loading');
+    el.setAttribute('aria-live', 'polite');
+    el.innerHTML = `${indent}<span class="lib-twistie-spacer"></span><span class="lib-name">Searching "${escapeHtml(row.query)}"...</span>`;
+    return;
+  }
+
+  el.classList.add('lib-row--loading');
+  el.innerHTML = `${indent}<span class="lib-twistie-spacer"></span><span class="lib-loader-dots" aria-hidden="true"><i></i><i></i><i></i></span><span class="lib-name">${escapeHtml(row.label || 'Loading')}</span>`;
+}
+
+function findFolderIdx(path: string): number {
+  return flat.findIndex(
+    (row) => row.kind === 'folder' && row.folder.path === path
+  );
+}
+
+function findAssetRow(publicId: string): Extract<Row, { kind: 'asset' }> | undefined {
+  const row = flat.find(
+    (item) => item.kind === 'asset' && item.asset.public_id === publicId
+  );
+  return row && row.kind === 'asset' ? row : undefined;
+}
+
+function findAssetIdx(publicId: string): number {
+  return flat.findIndex(
+    (item) => item.kind === 'asset' && item.asset.public_id === publicId
+  );
+}
+
+function collapseAt(idx: number): void {
+  const row = flat[idx];
+  if (row.kind !== 'folder') {
+    return;
+  }
+
+  row.expanded = false;
+  const end = spliceOutRangeAtDepth(
+    flat as Array<{ depth: number }>,
+    idx,
+    row.depth + 1
+  );
+
+  flat.splice(idx + 1, end - idx - 1);
+  rebuild();
+}
+
+function expandAt(idx: number, children: Row[]): void {
+  const row = flat[idx];
+  if (row.kind !== 'folder') {
+    return;
+  }
+
+  row.expanded = true;
+  flat.splice(idx + 1, 0, ...children);
+  rebuild();
+}
+
+function toggleFolder(path: string): void {
+  const idx = findFolderIdx(path);
+  if (idx < 0) {
+    return;
+  }
+
+  const row = flat[idx];
+  if (row.kind !== 'folder') {
+    return;
+  }
+
+  if (row.expanded) {
+    collapseAt(idx);
+    return;
+  }
+
+  const cached = childrenByFolder.get(path);
+  if (cached) {
+    expandAt(idx, cached);
+    return;
+  }
+
+  expandAt(idx, [{ kind: 'loading', depth: row.depth + 1 }]);
+  getVSCode()?.postMessage({ command: 'expandFolder', path });
+}
+
+function onRootData(folders: ClientFolder[], assets: ClientAsset[], hasMore: boolean): void {
+  const scrollSnapshot = snapshotScroll();
+  hideEmptyState();
+  clearError();
+  searchMode = null;
+  setSearchLoading(false);
+  setSearchInputValue('');
+  flat.length = 0;
+  childrenByFolder.clear();
+
+  for (const folder of folders) {
+    flat.push({ kind: 'folder', folder, depth: 0, expanded: false });
+  }
+
+  for (const asset of assets) {
+    flat.push({ kind: 'asset', asset, depth: 0 });
+  }
+
+  if (hasMore) {
+    flat.push({ kind: 'loading', label: 'Searching', depth: 0 });
+  }
+
+  if (flat.length > 0 && selectedIdx < 0) {
+    selectedIdx = 0;
+  } else if (selectedIdx >= flat.length) {
+    selectedIdx = flat.length - 1;
+  }
+
+  rebuild();
+  restoreScroll(scrollSnapshot);
+}
+
+function onRootAssetsAppended(assets: ClientAsset[], hasMore: boolean): void {
+  const loadingIdx = flat.findIndex((row) => row.kind === 'loading' && row.depth === 0);
+  if (loadingIdx >= 0) {
+    flat.splice(loadingIdx, 1);
+  }
+
+  for (const asset of assets) {
+    flat.push({ kind: 'asset', asset, depth: 0 });
+  }
+
+  if (hasMore) {
+    flat.push({ kind: 'loading', label: 'Searching', depth: 0 });
+  }
+
+  rebuild();
+}
+
+function onFolderData(
+  path: string,
+  folders: ClientFolder[],
+  assets: ClientAsset[],
+  hasMore: boolean
+): void {
+  const scrollSnapshot = snapshotScroll();
+  hideEmptyState();
+  clearError();
+  const idx = findFolderIdx(path);
+  if (idx < 0) {
+    return;
+  }
+
+  const row = flat[idx];
+  if (row.kind !== 'folder') {
+    return;
+  }
+
+  const depth = row.depth + 1;
+  const children: Row[] = [];
+
+  for (const folder of folders) {
+    children.push({ kind: 'folder', folder, depth, expanded: false });
+  }
+
+  for (const asset of assets) {
+    children.push({ kind: 'asset', asset, depth });
+  }
+
+  if (hasMore) {
+    children.push({ kind: 'loading', depth });
+  }
+
+  childrenByFolder.set(path, children.slice());
+
+  const end = spliceOutRangeAtDepth(
+    flat as Array<{ depth: number }>,
+    idx,
+    depth
+  );
+
+  flat.splice(idx + 1, end - idx - 1, ...children);
+  row.expanded = true;
+  rebuild();
+  restoreScroll(scrollSnapshot);
+}
+
+function onNestedAssetsAppended(
+  path: string,
+  assets: ClientAsset[],
+  hasMore: boolean
+): void {
+  const idx = findFolderIdx(path);
+  if (idx < 0) {
+    return;
+  }
+
+  const folderRow = flat[idx];
+  if (folderRow.kind !== 'folder') {
+    return;
+  }
+
+  const depth = folderRow.depth + 1;
+
+  const newRows: Row[] = assets.map((asset) => ({
+    kind: 'asset',
+    asset,
+    depth,
+  }));
+
+  if (hasMore) {
+    newRows.push({ kind: 'loading', depth });
+  }
+
+  const cachedChildren = childrenByFolder.get(path) || [];
+  const nextCachedChildren = cachedChildren.filter(
+    (child) => !(child.kind === 'loading' && child.depth === depth)
+  );
+  nextCachedChildren.push(...newRows);
+  childrenByFolder.set(path, nextCachedChildren);
+
+  if (!folderRow.expanded) {
+    return;
+  }
+
+  let end = spliceOutRangeAtDepth(
+    flat as Array<{ depth: number }>,
+    idx,
+    depth
+  );
+
+  if (end > idx + 1) {
+    const lastChild = flat[end - 1];
+    if (lastChild.kind === 'loading' && lastChild.depth === depth) {
+      flat.splice(end - 1, 1);
+      end--;
+    }
+  }
+
+  flat.splice(end, 0, ...newRows);
+
+  rebuild();
+}
+
+function onSearchData(query: string, assets: ClientAsset[], hasMore: boolean): void {
+  const currentQuery = getSearchInputQuery();
+  if (query !== currentQuery) {
+    return;
+  }
+
+  const scrollSnapshot = snapshotScroll();
+  hideEmptyState();
+  clearError();
+  searchMode = { query };
+  setSearchLoading(false);
+  setSearchInputValue(query);
+  flat.length = 0;
+  childrenByFolder.clear();
+  flat.push({ kind: 'clearSearch', label: `Clear search: ${query}`, depth: 0 });
+  for (const asset of assets) {
+    flat.push({ kind: 'asset', asset, depth: 0 });
+  }
+  if (hasMore) {
+    flat.push({ kind: 'loading', depth: 0 });
+  }
+  selectedIdx = flat.length > 0 ? 0 : -1;
+  rebuild();
+  restoreScroll(scrollSnapshot);
+}
+
+function onSearchAppended(assets: ClientAsset[], hasMore: boolean): void {
+  if (!searchMode || pendingSearchQuery) {
+    return;
+  }
+
+  const loadingIdx = flat.findIndex((row) => row.kind === 'loading');
+  if (loadingIdx >= 0) {
+    flat.splice(loadingIdx, 1);
+  }
+  for (const asset of assets) {
+    flat.push({ kind: 'asset', asset, depth: 0 });
+  }
+  if (hasMore) {
+    flat.push({ kind: 'loading', depth: 0 });
+  }
+  rebuild();
+}
+
+function onSearchPending(query: string): void {
+  setSearchInputValue(query);
+  showSearchPending(query);
+}
+
+function onEnvChanged(cloudName: string, hasConfig: boolean): void {
+  clearSearchDebounce();
+  clearError();
+  flat.length = 0;
+  childrenByFolder.clear();
+  searchMode = null;
+  setSearchLoading(false);
+  selectedIdx = -1;
+  rebuild();
+
+  const envEl = document.getElementById('lib-env');
+  if (envEl) {
+    envEl.textContent = hasConfig && cloudName ? cloudName : '';
+  }
+
+  // Reset inline search bar so stale queries do not survive an env switch.
+  const searchInput = document.getElementById('lib-search-input') as HTMLInputElement | null;
+  const searchClear = document.getElementById('lib-search-clear') as HTMLButtonElement | null;
+  if (searchInput) {
+    searchInput.value = '';
+  }
+  searchClear?.classList.add('hidden');
+
+  if (!hasConfig) {
+    showEmptyState('Connect your Cloudinary account to browse media', 'welcome');
+    return;
+  }
+
+  hideEmptyState();
+}
+
+window.addEventListener('message', (event: MessageEvent<InboundMessage>) => {
+  const message = event.data;
+  switch (message.command) {
+    case 'rootData':
+      onRootData(message.folders, message.assets, message.hasMore);
+      break;
+    case 'folderData':
+      onFolderData(
+        message.path,
+        message.folders,
+        message.assets,
+        message.hasMore
+      );
+      break;
+    case 'assetsAppended':
+      if (message.path === '') {
+        onRootAssetsAppended(message.assets, message.hasMore);
+      } else {
+        onNestedAssetsAppended(message.path, message.assets, message.hasMore);
+      }
+      break;
+    case 'searchData':
+      onSearchData(message.query, message.assets, message.hasMore);
+      break;
+    case 'searchAppended':
+      onSearchAppended(message.assets, message.hasMore);
+      break;
+    case 'searchPending':
+      onSearchPending(message.query);
+      break;
+    case 'envChanged':
+      onEnvChanged(message.cloudName, message.hasConfig);
+      break;
+    case 'viewStateChanged':
+      syncFilterUi(message.resourceTypeFilter, message.sortDirection);
+      break;
+    case 'error':
+      setSearchLoading(false);
+      showError(message.message);
+      break;
+    default:
+      break;
+  }
+});
+
+function initFilterBar(): void {
+  const typeSel = document.getElementById('lib-filter-type') as HTMLSelectElement | null;
+  const sortSel = document.getElementById('lib-filter-sort') as HTMLSelectElement | null;
+
+  const send = (): void => {
+    if (!typeSel || !sortSel) {
+      return;
+    }
+    getVSCode()?.postMessage({
+      command: 'setView',
+      resourceTypeFilter: typeSel.value,
+      sortDirection: sortSel.value,
+    });
+  };
+
+  typeSel?.addEventListener('change', send);
+  sortSel?.addEventListener('change', send);
+}
+
+function syncFilterUi(resourceTypeFilter: string, sortDirection: string): void {
+  const typeSel = document.getElementById('lib-filter-type') as HTMLSelectElement | null;
+  const sortSel = document.getElementById('lib-filter-sort') as HTMLSelectElement | null;
+  if (typeSel && typeSel.value !== resourceTypeFilter) {
+    typeSel.value = resourceTypeFilter;
+  }
+  if (sortSel && sortSel.value !== sortDirection) {
+    sortSel.value = sortDirection;
+  }
+}
+
+function setSearchInputValue(value: string): void {
+  const input = document.getElementById('lib-search-input') as HTMLInputElement | null;
+  const clearBtn = document.getElementById('lib-search-clear') as HTMLButtonElement | null;
+  if (input && input.value !== value) {
+    input.value = value;
+  }
+  clearBtn?.classList.toggle('hidden', value.trim() === '');
+}
+
+function getSearchInputQuery(): string {
+  const input = document.getElementById('lib-search-input') as HTMLInputElement | null;
+  return input?.value.trim() || '';
+}
+
+function clearSearchDebounce(): void {
+  if (searchDebounceTimer) {
+    window.clearTimeout(searchDebounceTimer);
+    searchDebounceTimer = null;
+  }
+}
+
+function setSearchLoading(isLoading: boolean, query?: string): void {
+  pendingSearchQuery = isLoading ? query || null : null;
+
+  const searchEl = document.getElementById('lib-search');
+  const input = document.getElementById('lib-search-input') as HTMLInputElement | null;
+  const clearBtn = document.getElementById('lib-search-clear') as HTMLButtonElement | null;
+  const loadingEl = document.getElementById('lib-search-loading');
+
+  searchEl?.classList.toggle('lib-search--loading', isLoading);
+  searchEl?.setAttribute('aria-busy', String(isLoading));
+  input?.setAttribute('aria-busy', String(isLoading));
+  loadingEl?.classList.toggle('hidden', !isLoading);
+
+  if (clearBtn) {
+    clearBtn.classList.toggle('hidden', isLoading || input?.value.trim() === '');
+  }
+}
+
+function showSearchPending(query: string): void {
+  hideEmptyState();
+  clearError();
+  searchMode = { query };
+  setSearchLoading(true, query);
+  flat.length = 0;
+  childrenByFolder.clear();
+  flat.push({ kind: 'searchLoading', query, depth: 0 });
+  selectedIdx = -1;
+  rebuild();
+}
+
+function submitSearch(query: string): void {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    clearSearchDebounce();
+    setSearchLoading(false);
+    if (searchMode || pendingSearchQuery) {
+      getVSCode()?.postMessage({ command: 'clearSearch' });
+    }
+    return;
+  }
+
+  clearSearchDebounce();
+  showSearchPending(trimmed);
+  requestSearch(trimmed);
+}
+
+function requestSearch(query: string): void {
+  getVSCode()?.postMessage({ command: 'searchAssets', query });
+}
+
+function scheduleSearch(query: string): void {
+  clearSearchDebounce();
+  const trimmed = query.trim();
+  if (!trimmed) {
+    submitSearch('');
+    return;
+  }
+
+  showSearchPending(trimmed);
+  searchDebounceTimer = window.setTimeout(() => {
+    searchDebounceTimer = null;
+    requestSearch(trimmed);
+  }, SEARCH_DEBOUNCE_MS);
+}
+
+function initSearchBar(): void {
+  const input = document.getElementById('lib-search-input') as HTMLInputElement | null;
+  const clearBtn = document.getElementById('lib-search-clear') as HTMLButtonElement | null;
+  if (!input) {
+    return;
+  }
+
+  input.addEventListener('input', () => {
+    if (pendingSearchQuery && input.value.trim() !== pendingSearchQuery) {
+      setSearchLoading(false);
+    }
+    clearBtn?.classList.toggle('hidden', input.value.trim() === '');
+    scheduleSearch(input.value);
+  });
+
+  input.addEventListener('keydown', (event) => {
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      submitSearch(input.value);
+      return;
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      if (input.value !== '') {
+        clearSearchDebounce();
+        setSearchLoading(false);
+        setSearchInputValue('');
+        getVSCode()?.postMessage({ command: 'clearSearch' });
+        return;
+      }
+      document.getElementById('lib-root')?.focus();
+    }
+  });
+
+  clearBtn?.addEventListener('click', () => {
+    clearSearchDebounce();
+    setSearchLoading(false);
+    setSearchInputValue('');
+    input.focus();
+    getVSCode()?.postMessage({ command: 'clearSearch' });
+  });
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  const container = document.getElementById('lib-root') as HTMLElement;
+  container.setAttribute('tabindex', '0');
+  list = new VirtualList<Row>({
+    container,
+    rowHeight: ROW_HEIGHT,
+    renderRow,
+  });
+  document.documentElement.style.setProperty('--lib-row-height', `${ROW_HEIGHT}px`);
+
+  initActionToolbar({
+    onAction: (action) => {
+      getVSCode()?.postMessage({ command: 'runToolbar', action });
+    },
+  });
+
+  initSearchBar();
+  initFilterBar();
+
+  container.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement;
+    const rowEl = target.closest('.lib-row') as HTMLElement | null;
+    if (!rowEl) {
+      return;
+    }
+
+    if (rowEl.classList.contains('lib-row--folder')) {
+      const path = rowEl.dataset.path || '';
+      const idx = findFolderIdx(path);
+      setSelected(idx);
+      toggleFolder(path);
+      return;
+    }
+
+    if (rowEl.classList.contains('lib-row--clear')) {
+      setSelected(0);
+      getVSCode()?.postMessage({ command: 'clearSearch' });
+      return;
+    }
+
+    if (rowEl.classList.contains('lib-row--asset')) {
+      const publicId = rowEl.dataset.publicId || '';
+      const idx = findAssetIdx(publicId);
+      setSelected(idx);
+      const row = findAssetRow(publicId);
+      if (row) {
+        getVSCode()?.postMessage({ command: 'openAsset', asset: row.asset });
+      }
+    }
+  });
+
+  container.addEventListener('contextmenu', (event) => {
+    event.preventDefault();
+
+    const rowEl = (event.target as HTMLElement).closest('.lib-row') as HTMLElement | null;
+    if (!rowEl) {
+      return;
+    }
+
+    if (rowEl.classList.contains('lib-row--asset')) {
+      const publicId = rowEl.dataset.publicId || '';
+      const row = findAssetRow(publicId);
+      if (!row) {
+        return;
+      }
+
+      setSelected(findAssetIdx(publicId));
+      showMenu(
+        event.clientX,
+        event.clientY,
+        [
+          { label: 'Copy URL', action: 'copyUrl', icon: menuIcons.link() },
+          { label: 'Copy Public ID', action: 'copyPublicId', icon: menuIcons.hash() },
+          {
+            label: 'Copy Optimized URL',
+            action: 'copyOptimizedUrl',
+            icon: menuIcons.bolt(),
+          },
+        ],
+        (action) => {
+          getVSCode()?.postMessage({
+            command: 'contextAction',
+            action,
+            data: row.asset,
+          });
+        }
+      );
+      return;
+    }
+
+    if (rowEl.classList.contains('lib-row--folder')) {
+      const path = rowEl.dataset.path || '';
+      const idx = findFolderIdx(path);
+      const row = idx >= 0 ? flat[idx] : undefined;
+      if (!row || row.kind !== 'folder') {
+        return;
+      }
+
+      setSelected(idx);
+      showMenu(
+        event.clientX,
+        event.clientY,
+        [
+          {
+            label: 'Upload here',
+            action: 'uploadToFolder',
+            icon: menuIcons.upload(),
+          },
+        ],
+        (action) => {
+          getVSCode()?.postMessage({
+            command: 'contextAction',
+            action,
+            data: row.folder,
+          });
+        }
+      );
+    }
+  });
+
+  container.addEventListener('keydown', (event) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      setSelected(selectedIdx + 1);
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      setSelected(selectedIdx - 1);
+    } else if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      const row = flat[selectedIdx];
+      if (row && row.kind === 'folder' && !row.expanded) {
+        toggleFolder(row.folder.path);
+      }
+    } else if (event.key === 'ArrowLeft') {
+      event.preventDefault();
+      const row = flat[selectedIdx];
+      if (row && row.kind === 'folder' && row.expanded) {
+        toggleFolder(row.folder.path);
+      }
+    } else if (event.key === 'Enter') {
+      event.preventDefault();
+      const row = flat[selectedIdx];
+      if (row?.kind === 'asset') {
+        getVSCode()?.postMessage({ command: 'openAsset', asset: row.asset });
+      } else if (row?.kind === 'folder') {
+        toggleFolder(row.folder.path);
+      } else if (row?.kind === 'clearSearch') {
+        getVSCode()?.postMessage({ command: 'clearSearch' });
+      }
+    }
+  });
+
+  getVSCode()?.postMessage({ command: 'ready' });
+});
diff --git a/src/webview/client/libraryIcons.ts b/src/webview/client/libraryIcons.ts
new file mode 100644
index 0000000..b271aa6
--- /dev/null
+++ b/src/webview/client/libraryIcons.ts
@@ -0,0 +1,77 @@
+const ICON_SIZE = 14;
+
+function icon(body: string): string {
+  return `<svg width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+}
+
+function filled(body: string, extra = ''): string {
+  return `<svg width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"${extra ? ` ${extra}` : ''}>${body}</svg>`;
+}
+
+export const rowIcons = {
+  chevron: () =>
+    `<svg width="10" height="10" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 4l4 4-4 4"/></svg>`,
+
+  folder: () =>
+    icon(
+      '<path d="M3 6.25a1.25 1.25 0 0 1 1.25-1.25h3.6a1 1 0 0 1 .78.37l1.2 1.5a1 1 0 0 0 .78.38h5.14A1.25 1.25 0 0 1 17 8.5v7.25A1.25 1.25 0 0 1 15.75 17H4.25A1.25 1.25 0 0 1 3 15.75V6.25z"/>'
+    ),
+
+  folderOpen: () =>
+    filled(
+      '<path d="M3 6.25a1.25 1.25 0 0 1 1.25-1.25h3.6a1 1 0 0 1 .78.37l1.2 1.5a1 1 0 0 0 .78.38h5.14A1.25 1.25 0 0 1 17 8.5v.5H3V6.25z"/><path d="M3.1 10h13.8l-1.06 5.55A1.5 1.5 0 0 1 14.37 17H4.63a1.5 1.5 0 0 1-1.47-1.45L3.1 10z" opacity="0.85"/>'
+    ),
+
+  image: () =>
+    `<svg width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2.5" y="3.5" width="15" height="13" rx="1.5"/><circle cx="7" cy="8" r="1.3" fill="currentColor"/><path d="M3 14.5l4.3-4 3.2 2.6 2.5-2 4.5 3.9"/></svg>`,
+
+  video: () =>
+    `<svg width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 20 20" fill="currentColor" fill-rule="evenodd" aria-hidden="true"><path d="M3 5.5A1.5 1.5 0 0 1 4.5 4h11A1.5 1.5 0 0 1 17 5.5v9a1.5 1.5 0 0 1-1.5 1.5h-11A1.5 1.5 0 0 1 3 14.5v-9zm5.5 2.2v4.6l4-2.3-4-2.3z"/></svg>`,
+
+  file: () =>
+    `<svg width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 20 20" aria-hidden="true"><path fill="currentColor" fill-rule="evenodd" d="M5.5 2.5h5.3l3.7 3.7v9.8a1.5 1.5 0 0 1-1.5 1.5h-7.5A1.5 1.5 0 0 1 4 16V4a1.5 1.5 0 0 1 1.5-1.5zm5 0v3.7h3.7"/></svg>`,
+
+  close: () =>
+    `<svg width="10" height="10" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>`,
+
+  lock: () =>
+    `<svg width="11" height="11" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.45" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3.5" y="7" width="9" height="6.5" rx="1.2"/><path d="M5.5 7V5a2.5 2.5 0 0 1 5 0v2"/></svg>`,
+};
+
+export function assetIcon(resourceType: 'image' | 'video' | 'raw'): string {
+  if (resourceType === 'video') {
+    return rowIcons.video();
+  }
+  if (resourceType === 'raw') {
+    return rowIcons.file();
+  }
+  return rowIcons.image();
+}
+
+export function folderIcon(expanded: boolean): string {
+  return expanded ? rowIcons.folderOpen() : rowIcons.folder();
+}
+
+const MENU_ICON_SIZE = 14;
+
+function menuSvg(body: string, viewBox = '0 0 24 24'): string {
+  return `<svg width="${MENU_ICON_SIZE}" height="${MENU_ICON_SIZE}" viewBox="${viewBox}" fill="currentColor" aria-hidden="true">${body}</svg>`;
+}
+
+export const menuIcons = {
+  link: () =>
+    menuSvg(
+      '<path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/>'
+    ),
+
+  hash: () =>
+    menuSvg(
+      '<path d="M20 7h-4l1-4h-2l-1 4h-4l1-4h-2L8 7H4v2h3.5L6.5 13H3v2h3l-1 4h2l1-4h4l-1 4h2l1-4h4v-2h-3.5l1-4H20V7zm-5.5 6h-4l1-4h4l-1 4z"/>'
+    ),
+
+  bolt: () =>
+    menuSvg('<path d="M7 2v11h3v9l7-12h-4l4-8z"/>'),
+
+  upload: () =>
+    menuSvg('<path d="M9 16h6v-6h4l-7-7-7 7h4v6zm-4 2h14v2H5v-2z"/>'),
+};
diff --git a/src/webview/client/libraryMenu.ts b/src/webview/client/libraryMenu.ts
new file mode 100644
index 0000000..802dc81
--- /dev/null
+++ b/src/webview/client/libraryMenu.ts
@@ -0,0 +1,251 @@
+const MENU_ID = '__lib-menu__';
+const VIEWPORT_MARGIN = 8;
+
+export interface MenuItem {
+  label: string;
+  action: string;
+  /** Optional inline SVG markup rendered before the label. */
+  icon?: string;
+  /** Render a separator before this item. */
+  divider?: boolean;
+}
+
+interface MenuState {
+  el: HTMLElement;
+  items: HTMLButtonElement[];
+  highlighted: number;
+  onPick: (action: string) => void;
+}
+
+let active: MenuState | undefined;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (max < min) {
+    return min;
+  }
+  return Math.max(min, Math.min(max, value));
+}
+
+function highlight(state: MenuState, idx: number): void {
+  if (state.items.length === 0) {
+    return;
+  }
+  const wrapped =
+    ((idx % state.items.length) + state.items.length) % state.items.length;
+  if (state.highlighted === wrapped) {
+    return;
+  }
+  if (state.highlighted >= 0 && state.items[state.highlighted]) {
+    state.items[state.highlighted].classList.remove('lib-menu-item--active');
+    state.items[state.highlighted].removeAttribute('aria-current');
+  }
+  state.highlighted = wrapped;
+  const next = state.items[wrapped];
+  next.classList.add('lib-menu-item--active');
+  next.setAttribute('aria-current', 'true');
+}
+
+function pick(state: MenuState, idx: number): void {
+  const item = state.items[idx];
+  if (!item) {
+    return;
+  }
+  const action = item.dataset.action;
+  hideMenu();
+  if (action) {
+    state.onPick(action);
+  }
+}
+
+function onDocumentMouseDown(event: MouseEvent): void {
+  if (!active) {
+    return;
+  }
+  const target = event.target;
+  if (target instanceof Node && active.el.contains(target)) {
+    return;
+  }
+  hideMenu();
+}
+
+function onWindowDismiss(): void {
+  hideMenu();
+}
+
+function onKey(event: KeyboardEvent): void {
+  if (!active) {
+    return;
+  }
+  if (event.key === 'Escape') {
+    event.preventDefault();
+    event.stopPropagation();
+    hideMenu();
+    return;
+  }
+  if (event.key === 'ArrowDown') {
+    event.preventDefault();
+    highlight(active, active.highlighted + 1);
+    return;
+  }
+  if (event.key === 'ArrowUp') {
+    event.preventDefault();
+    highlight(active, active.highlighted - 1);
+    return;
+  }
+  if (event.key === 'Home') {
+    event.preventDefault();
+    highlight(active, 0);
+    return;
+  }
+  if (event.key === 'End') {
+    event.preventDefault();
+    highlight(active, active.items.length - 1);
+    return;
+  }
+  if (event.key === 'Enter' || event.key === ' ') {
+    if (active.highlighted >= 0) {
+      event.preventDefault();
+      pick(active, active.highlighted);
+    }
+  }
+}
+
+function attachListeners(): void {
+  document.addEventListener('mousedown', onDocumentMouseDown, true);
+  document.addEventListener('keydown', onKey, true);
+  window.addEventListener('blur', onWindowDismiss);
+  window.addEventListener('resize', onWindowDismiss);
+}
+
+function detachListeners(): void {
+  document.removeEventListener('mousedown', onDocumentMouseDown, true);
+  document.removeEventListener('keydown', onKey, true);
+  window.removeEventListener('blur', onWindowDismiss);
+  window.removeEventListener('resize', onWindowDismiss);
+}
+
+function positionMenu(menu: HTMLElement, anchorX: number, anchorY: number): void {
+  // Insert offscreen for measurement.
+  menu.style.left = '-9999px';
+  menu.style.top = '-9999px';
+  menu.style.visibility = 'hidden';
+  document.body.appendChild(menu);
+
+  const rect = menu.getBoundingClientRect();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const maxLeft = Math.max(VIEWPORT_MARGIN, vw - rect.width - VIEWPORT_MARGIN);
+  const maxTop = Math.max(VIEWPORT_MARGIN, vh - rect.height - VIEWPORT_MARGIN);
+
+  // Horizontal: prefer right of cursor; flip to left of cursor if overflow;
+  // finally clamp.
+  let left = anchorX;
+  if (left + rect.width + VIEWPORT_MARGIN > vw) {
+    const flipped = anchorX - rect.width;
+    left = flipped >= VIEWPORT_MARGIN ? flipped : maxLeft;
+  }
+  left = clamp(left, VIEWPORT_MARGIN, maxLeft);
+
+  // Vertical: prefer below cursor; flip above; clamp.
+  let top = anchorY;
+  if (top + rect.height + VIEWPORT_MARGIN > vh) {
+    const flipped = anchorY - rect.height;
+    top = flipped >= VIEWPORT_MARGIN ? flipped : maxTop;
+  }
+  top = clamp(top, VIEWPORT_MARGIN, maxTop);
+
+  menu.style.left = `${left}px`;
+  menu.style.top = `${top}px`;
+  menu.style.visibility = '';
+}
+
+function buildMenu(items: MenuItem[]): { el: HTMLElement; itemEls: HTMLButtonElement[] } {
+  const el = document.createElement('div');
+  el.className = 'lib-menu';
+  el.id = MENU_ID;
+  el.setAttribute('role', 'menu');
+  el.style.position = 'fixed';
+
+  const itemEls: HTMLButtonElement[] = [];
+
+  for (const item of items) {
+    if (item.divider) {
+      const sep = document.createElement('div');
+      sep.className = 'lib-menu__divider';
+      sep.setAttribute('role', 'separator');
+      el.appendChild(sep);
+    }
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'lib-menu-item';
+    btn.setAttribute('role', 'menuitem');
+    btn.dataset.action = item.action;
+    btn.tabIndex = -1;
+
+    const iconMarkup = item.icon
+      ? `<span class="lib-menu-item__icon">${item.icon}</span>`
+      : '<span class="lib-menu-item__icon" aria-hidden="true"></span>';
+    btn.innerHTML = `${iconMarkup}<span class="lib-menu-item__label">${escapeHtml(item.label)}</span>`;
+
+    el.appendChild(btn);
+    itemEls.push(btn);
+  }
+
+  return { el, itemEls };
+}
+
+export function showMenu(
+  anchorX: number,
+  anchorY: number,
+  items: MenuItem[],
+  onPick: (action: string) => void
+): void {
+  hideMenu();
+
+  if (items.length === 0) {
+    return;
+  }
+
+  const { el, itemEls } = buildMenu(items);
+  const state: MenuState = {
+    el,
+    items: itemEls,
+    highlighted: -1,
+    onPick,
+  };
+
+  positionMenu(el, anchorX, anchorY);
+
+  itemEls.forEach((btn, idx) => {
+    btn.addEventListener('click', () => pick(state, idx));
+    btn.addEventListener('mouseenter', () => highlight(state, idx));
+  });
+
+  active = state;
+  highlight(state, 0);
+
+  // Defer to skip the contextmenu event tail.
+  setTimeout(() => {
+    if (active === state) {
+      attachListeners();
+    }
+  }, 0);
+}
+
+export function hideMenu(): void {
+  if (!active) {
+    document.getElementById(MENU_ID)?.remove();
+    return;
+  }
+  detachListeners();
+  active.el.remove();
+  active = undefined;
+}
diff --git a/src/webview/client/libraryRowSplice.ts b/src/webview/client/libraryRowSplice.ts
new file mode 100644
index 0000000..fd36984
--- /dev/null
+++ b/src/webview/client/libraryRowSplice.ts
@@ -0,0 +1,16 @@
+/**
+ * Returns the index (exclusive) of the first row after `startIdx` whose depth
+ * is strictly less than `depth`. Use this to find where a folder's children
+ * block ends in the flat row array.
+ */
+export function spliceOutRangeAtDepth(
+  rows: Array<{ depth: number }>,
+  startIdx: number,
+  depth: number,
+): number {
+  let i = startIdx + 1;
+  while (i < rows.length && rows[i].depth >= depth) {
+    i++;
+  }
+  return i;
+}
diff --git a/src/webview/client/libraryTypes.ts b/src/webview/client/libraryTypes.ts
new file mode 100644
index 0000000..6963900
--- /dev/null
+++ b/src/webview/client/libraryTypes.ts
@@ -0,0 +1,58 @@
+export interface ClientAsset {
+  public_id: string;
+  display_name?: string;
+  resource_type: 'image' | 'video' | 'raw';
+  type?: string;
+  format?: string;
+  bytes?: number;
+  width?: number;
+  height?: number;
+  secure_url: string;
+  optimized_url: string;
+  thumbnail_url: string;
+  tags?: string[];
+  context?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface ClientFolder {
+  name: string;
+  path: string;
+}
+
+export type ResourceTypeFilter = 'all' | 'image' | 'video' | 'raw';
+export type SortDirection = 'asc' | 'desc';
+
+export type InboundMessage =
+  | { command: 'rootData'; folders: ClientFolder[]; assets: ClientAsset[]; hasMore: boolean }
+  | { command: 'folderData'; path: string; folders: ClientFolder[]; assets: ClientAsset[]; hasMore: boolean }
+  | { command: 'assetsAppended'; path: string; assets: ClientAsset[]; hasMore: boolean }
+  | { command: 'searchData'; query: string; assets: ClientAsset[]; hasMore: boolean }
+  | { command: 'searchAppended'; assets: ClientAsset[]; hasMore: boolean }
+  | { command: 'searchPending'; query: string }
+  | { command: 'envChanged'; cloudName: string; folderMode: 'dynamic' | 'fixed'; hasConfig: boolean }
+  | {
+      command: 'viewStateChanged';
+      resourceTypeFilter: ResourceTypeFilter;
+      sortDirection: SortDirection;
+    }
+  | { command: 'error'; message: string }
+  | { command: 'focusSearch' };
+
+export type OutboundMessage =
+  | { command: 'ready' }
+  | { command: 'expandFolder'; path: string }
+  | { command: 'openAsset'; asset: ClientAsset }
+  | {
+      command: 'contextAction';
+      action: 'copyUrl' | 'copyPublicId' | 'copyOptimizedUrl' | 'uploadToFolder';
+      data: ClientAsset | ClientFolder;
+    }
+  | {
+      command: 'runToolbar';
+      action: 'refresh' | 'openUploadWidget' | 'showHomescreen' | 'openGlobalConfig';
+    }
+  | { command: 'setView'; resourceTypeFilter: ResourceTypeFilter; sortDirection: SortDirection }
+  | { command: 'searchAssets'; query: string }
+  | { command: 'clearSearch' };
diff --git a/src/webview/client/libraryVirtualList.ts b/src/webview/client/libraryVirtualList.ts
new file mode 100644
index 0000000..48dc352
--- /dev/null
+++ b/src/webview/client/libraryVirtualList.ts
@@ -0,0 +1,119 @@
+/// <reference lib="dom" />
+
+export interface WindowInput {
+  scrollTop: number;
+  viewportHeight: number;
+  rowHeight: number;
+  totalRows: number;
+  buffer: number;
+}
+
+export interface WindowRange {
+  startIdx: number;
+  endIdx: number;
+  startOffset: number;
+  totalHeight: number;
+}
+
+export function computeWindow(input: WindowInput): WindowRange {
+  const firstVisible = Math.floor(input.scrollTop / input.rowHeight);
+  const visibleCount = Math.ceil(input.viewportHeight / input.rowHeight);
+  const startIdx = Math.max(0, firstVisible - input.buffer);
+  const endIdx = Math.min(
+    input.totalRows,
+    firstVisible + visibleCount + input.buffer
+  );
+
+  return {
+    startIdx,
+    endIdx,
+    startOffset: startIdx * input.rowHeight,
+    totalHeight: input.totalRows * input.rowHeight,
+  };
+}
+
+export interface VirtualListOpts<T> {
+  container: HTMLElement;
+  rowHeight: number | (() => number);
+  buffer?: number;
+  renderRow(el: HTMLElement, item: T, index: number): void;
+}
+
+/**
+ * Simple fixed-row-height virtual list. Rows are recycled from a pool.
+ */
+export class VirtualList<T> {
+  private items: T[] = [];
+  private readonly getRowHeight: () => number;
+  private readonly buffer: number;
+  private readonly container: HTMLElement;
+  private readonly spacer: HTMLDivElement;
+  private readonly pool: HTMLDivElement[] = [];
+  private readonly renderRow: (el: HTMLElement, item: T, index: number) => void;
+
+  constructor(opts: VirtualListOpts<T>) {
+    this.container = opts.container;
+    const rowHeight = opts.rowHeight;
+    this.getRowHeight = typeof rowHeight === 'function'
+      ? rowHeight
+      : () => rowHeight;
+    this.buffer = opts.buffer ?? 5;
+    this.renderRow = opts.renderRow;
+
+    this.container.style.position = 'relative';
+    this.container.style.overflowY = 'auto';
+
+    this.spacer = document.createElement('div');
+    this.spacer.style.position = 'relative';
+    this.spacer.style.width = '100%';
+    this.container.appendChild(this.spacer);
+
+    this.container.addEventListener('scroll', () => this.render());
+  }
+
+  setItems(items: T[]): void {
+    this.items = items;
+    this.render();
+  }
+
+  appendItems(more: T[]): void {
+    this.items = this.items.concat(more);
+    this.render();
+  }
+
+  render(): void {
+    const rowHeight = this.getRowHeight();
+    const windowRange = computeWindow({
+      scrollTop: this.container.scrollTop,
+      viewportHeight: this.container.clientHeight,
+      rowHeight,
+      totalRows: this.items.length,
+      buffer: this.buffer,
+    });
+
+    this.spacer.style.height = `${windowRange.totalHeight}px`;
+
+    const needed = windowRange.endIdx - windowRange.startIdx;
+    while (this.pool.length < needed) {
+      const row = document.createElement('div');
+      row.style.position = 'absolute';
+      row.style.left = '0';
+      row.style.right = '0';
+      this.spacer.appendChild(row);
+      this.pool.push(row);
+    }
+
+    for (let i = 0; i < this.pool.length; i++) {
+      const row = this.pool[i];
+      row.style.height = `${rowHeight}px`;
+      if (i < needed) {
+        const idx = windowRange.startIdx + i;
+        row.style.top = `${idx * rowHeight}px`;
+        row.style.display = '';
+        this.renderRow(row, this.items[idx], idx);
+      } else {
+        row.style.display = 'none';
+      }
+    }
+  }
+}
diff --git a/src/webview/client/upload-widget.ts b/src/webview/client/upload-widget.ts
index afd73ec..a3c67c7 100644
--- a/src/webview/client/upload-widget.ts
+++ b/src/webview/client/upload-widget.ts
@@ -9,9 +9,11 @@ import {
   truncateString,
   copyToClipboard,
 } from "./common";
+import { buildUploadPresetOptions } from "./uploadPresetOptions";
 
 interface UploadPreset {
   name: string;
+  signed?: boolean;
   settings?: Record<string, unknown>;
 }
 
@@ -24,6 +26,7 @@ interface AssetData {
   public_id: string;
   secure_url: string;
   resource_type: string;
+  type?: string;
   _uploadedToFolder?: string;
 }
 
@@ -35,16 +38,41 @@ interface UploadMessage {
   error?: string;
   folderPath?: string;
   folders?: Array<{ path: string; label: string }>;
+  preset?: string;
+  presets?: UploadPreset[];
 }
 
 // Configuration
 let cloudName = "";
 let presets: UploadPreset[] = [];
 
+function replaceSelectOptions(
+  select: HTMLSelectElement,
+  options: Array<{ value: string; label: string }>,
+  selectedValue: string
+): void {
+  const nextOptions = [...options];
+  if (selectedValue && !nextOptions.some((option) => option.value === selectedValue)) {
+    nextOptions.push({ value: selectedValue, label: selectedValue });
+  }
+
+  select.replaceChildren(
+    ...nextOptions.map((item) => {
+      const option = document.createElement("option");
+      option.value = item.value;
+      option.textContent = item.label;
+      option.selected = item.value === selectedValue;
+      return option;
+    })
+  );
+}
+
 /**
  * Initialize upload widget with configuration.
  */
 function initUploadWidget(config: UploadConfig): void {
+  initCommon();
+
   cloudName = config.cloudName || "";
   presets = config.presets || [];
 
@@ -53,6 +81,8 @@ function initUploadWidget(config: UploadConfig): void {
   initUrlUpload();
   initClearButton();
   initFolderChange();
+
+  getVSCode()?.postMessage({ command: "ready" });
 }
 
 /**
@@ -365,6 +395,10 @@ function getThumbnailUrl(asset: AssetData): string | null {
   const publicId = asset.public_id;
   const resourceType = asset.resource_type;
 
+  if (asset.type === "authenticated") {
+    return resourceType === "image" ? asset.secure_url : null;
+  }
+
   if (resourceType === "image") {
     return `https://res.cloudinary.com/${cloudName}/image/upload/w_130,h_100,c_fill,g_auto,f_auto,q_auto/${publicId}`;
   } else if (resourceType === "video") {
@@ -514,13 +548,33 @@ function handleUploadMessage(message: UploadMessage): void {
       if (message.folders) {
         const folderSelect = document.getElementById("folderSelect") as HTMLSelectElement | null;
         if (folderSelect) {
-          const currentValue = folderSelect.value;
-          folderSelect.innerHTML = message.folders
-            .map(
-              (f) =>
-                `<option value="${f.path}" ${f.path === currentValue ? "selected" : ""}>${f.label}</option>`
-            )
-            .join("");
+          const selectedValue = message.folderPath !== undefined ? message.folderPath : folderSelect.value;
+          replaceSelectOptions(
+            folderSelect,
+            message.folders.map((folder) => ({ value: folder.path, label: folder.label })),
+            selectedValue
+          );
+        }
+        // Folders have arrived (or failed back to root): drop the loading hint.
+        const loadingHint = document.getElementById("folderLoadingHint");
+        if (loadingHint) {
+          loadingHint.remove();
+        }
+      }
+      break;
+
+    case "updatePresets":
+      if (Array.isArray(message.presets)) {
+        presets = message.presets;
+        const presetSelect = document.getElementById("presetSelect") as HTMLSelectElement | null;
+        if (presetSelect) {
+          const selectedValue = message.preset !== undefined ? message.preset : presetSelect.value;
+          replaceSelectOptions(
+            presetSelect,
+            buildUploadPresetOptions(presets),
+            selectedValue
+          );
+          presetSelect.dispatchEvent(new Event("change"));
         }
       }
       break;
@@ -540,6 +594,3 @@ declare global {
 }
 
 window.initUploadWidget = initUploadWidget;
-
-// Also run initCommon when this script loads
-initCommon();
diff --git a/src/webview/client/uploadPresetOptions.ts b/src/webview/client/uploadPresetOptions.ts
new file mode 100644
index 0000000..90b13ca
--- /dev/null
+++ b/src/webview/client/uploadPresetOptions.ts
@@ -0,0 +1,19 @@
+export interface UploadPresetOptionInput {
+  name: string;
+  signed?: boolean;
+}
+
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+export function buildUploadPresetOptions(presets: UploadPresetOptionInput[]): SelectOption[] {
+  return [
+    { value: "", label: "No preset (signed upload)" },
+    ...presets.map((preset) => ({
+      value: preset.name,
+      label: `${preset.name} (${preset.signed ? "Signed" : "Unsigned"})`,
+    })),
+  ];
+}
diff --git a/src/webview/client/welcome.ts b/src/webview/client/welcome.ts
index 533f32c..2be56c0 100644
--- a/src/webview/client/welcome.ts
+++ b/src/webview/client/welcome.ts
@@ -2,7 +2,7 @@
  * Welcome Screen specific functionality.
  */
 
-import { initCommon, getVSCode } from "./common";
+import { copyToClipboard, initCommon, getVSCode } from "./common";
 
 /**
  * Open global configuration file.
@@ -21,8 +21,8 @@ function openExternal(url: string): void {
 /**
  * Focus the Cloudinary sidebar (opens the dashboard).
  */
-function focusTreeView(): void {
-  getVSCode()?.postMessage({ command: "focusTreeView" });
+function focusDashboard(): void {
+  getVSCode()?.postMessage({ command: "focusDashboard" });
 }
 
 /**
@@ -46,15 +46,43 @@ declare global {
   interface Window {
     openGlobalConfig: typeof openGlobalConfig;
     openExternal: typeof openExternal;
-    focusTreeView: typeof focusTreeView;
+    focusDashboard: typeof focusDashboard;
     getConfigExample: typeof getConfigExample;
   }
 }
 
 window.openGlobalConfig = openGlobalConfig;
 window.openExternal = openExternal;
-window.focusTreeView = focusTreeView;
+window.focusDashboard = focusDashboard;
 window.getConfigExample = getConfigExample;
 
 // Initialize common functionality when this script loads
 initCommon();
+
+document.addEventListener("click", async (event) => {
+  const target = (event.target as HTMLElement | null)?.closest(
+    "[data-welcome-action]"
+  ) as HTMLElement | null;
+
+  if (!target) {return;}
+
+  event.preventDefault();
+  const action = target.dataset.welcomeAction;
+
+  switch (action) {
+    case "openGlobalConfig":
+      openGlobalConfig();
+      break;
+    case "focusDashboard":
+      focusDashboard();
+      break;
+    case "openExternal":
+      if (target.dataset.url) {
+        openExternal(target.dataset.url);
+      }
+      break;
+    case "copyConfigExample":
+      await copyToClipboard(getConfigExample(), target);
+      break;
+  }
+});
diff --git a/src/webview/components/actionToolbar.ts b/src/webview/components/actionToolbar.ts
new file mode 100644
index 0000000..b394ea0
--- /dev/null
+++ b/src/webview/components/actionToolbar.ts
@@ -0,0 +1,88 @@
+import { actionIcons, IconSize } from "../icons";
+
+export type ActionToolbarItemId = "home" | "refresh" | "upload" | "settings";
+
+interface ActionToolbarItem {
+  id: ActionToolbarItemId;
+  action: string;
+  label: string;
+  title: string;
+  icon: (size: IconSize) => string;
+  group: "primary" | "upload" | "utility";
+}
+
+interface RenderActionToolbarOptions {
+  id: string;
+  ariaLabel: string;
+  items?: ActionToolbarItemId[];
+}
+
+const defaultItems: ActionToolbarItem[] = [
+  {
+    id: "home",
+    action: "showHomescreen",
+    label: "Home",
+    title: "Home",
+    icon: actionIcons.home,
+    group: "primary",
+  },
+  {
+    id: "refresh",
+    action: "refresh",
+    label: "Refresh",
+    title: "Refresh",
+    icon: actionIcons.refresh,
+    group: "primary",
+  },
+  {
+    id: "upload",
+    action: "openUploadWidget",
+    label: "Upload",
+    title: "Upload",
+    icon: actionIcons.upload,
+    group: "upload",
+  },
+  {
+    id: "settings",
+    action: "openGlobalConfig",
+    label: "Configuration",
+    title: "Configuration",
+    icon: actionIcons.settings,
+    group: "utility",
+  },
+];
+
+export function renderActionToolbar(options: RenderActionToolbarOptions): string {
+  const visibleItems = options.items
+    ? defaultItems.filter((item) => options.items?.includes(item.id))
+    : defaultItems;
+  const groups = ["primary", "upload", "utility"] as const;
+  const groupHtml = groups
+    .map((group) => {
+      const items = visibleItems.filter((item) => item.group === group);
+      if (items.length === 0) {
+        return "";
+      }
+      const buttons = items
+        .map((item) => `
+          <button
+            class="cld-action-toolbar__button"
+            type="button"
+            data-action="${item.action}"
+            title="${item.title}"
+            aria-label="${item.label}"
+          >${item.icon("sm")}</button>
+        `)
+        .join("");
+
+      const utilityClass = group === "utility" ? " cld-action-toolbar__group--utility" : "";
+      return `<div class="cld-action-toolbar__group${utilityClass}">${buttons}</div>`;
+    })
+    .join("");
+
+  return `
+    <div id="${options.id}" class="cld-action-toolbar" role="toolbar" aria-label="${options.ariaLabel}" data-cld-action-toolbar>
+      ${groupHtml}
+    </div>
+  `;
+}
diff --git a/src/webview/components/dropZone.ts b/src/webview/components/dropZone.ts
index 2ac43da..d1f1272 100644
--- a/src/webview/components/dropZone.ts
+++ b/src/webview/components/dropZone.ts
@@ -327,7 +327,7 @@ export const fileIcon = `
  * @example
  * ```typescript
  * createDropZone({
- *   text: 'Drag & drop files here',
+ *   text: 'Hold Shift, then drag & drop files here',
  *   hint: '— or —',
  *   buttonText: 'Browse Files',
  *   inputId: 'fileInput',
@@ -337,7 +337,7 @@ export const fileIcon = `
  */
 export function createDropZone(options: DropZoneOptions = {}): string {
   const {
-    text = "Drag & drop files here",
+    text = "Hold Shift, then drag & drop files here",
     hint = "— or —",
     buttonText = "Browse Files",
     inputId = "fileInput",
@@ -428,7 +428,7 @@ export function createUploadedAssetsSection(
   return `
     <div id="uploaded-assets" class="uploaded-assets hidden">
       <div class="uploaded-assets__header">
-        <h3 class="uploaded-assets__title">✅ ${escapeHtml(title)}</h3>
+        <h3 class="uploaded-assets__title">${escapeHtml(title)}</h3>
         ${clearButtonHtml}
       </div>
       <div id="asset-grid" class="asset-grid">
@@ -437,4 +437,3 @@ export function createUploadedAssetsSection(
     </div>
   `;
 }
-
diff --git a/src/webview/docsAiConfig.ts b/src/webview/docsAiConfig.ts
new file mode 100644
index 0000000..fb6b8f0
--- /dev/null
+++ b/src/webview/docsAiConfig.ts
@@ -0,0 +1,33 @@
+import * as vscode from "vscode";
+
+export const DEFAULT_DOCS_AI_API_BASE = "https://cld-docs-ai-delta.vercel.app";
+
+export function normalizeDocsAiApiBase(value: unknown): string {
+  const rawValue = typeof value === "string" ? value.trim() : "";
+
+  if (!rawValue) {
+    return DEFAULT_DOCS_AI_API_BASE;
+  }
+
+  try {
+    const url = new URL(rawValue);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      return DEFAULT_DOCS_AI_API_BASE;
+    }
+
+    url.hash = "";
+    url.search = "";
+
+    return url.href.replace(/\/+$/, "");
+  } catch {
+    return DEFAULT_DOCS_AI_API_BASE;
+  }
+}
+
+export function getDocsAiApiBase(): string {
+  const configuredBase = vscode.workspace
+    .getConfiguration()
+    .get<string>("cloudinary.docsAi.apiBase");
+
+  return normalizeDocsAiApiBase(configuredBase);
+}
diff --git a/src/webview/docsAiView.ts b/src/webview/docsAiView.ts
new file mode 100644
index 0000000..6c4da5a
--- /dev/null
+++ b/src/webview/docsAiView.ts
@@ -0,0 +1,273 @@
+import * as vscode from "vscode";
+import { AnalyticsService, type AnalyticsPayload } from "../analytics/analyticsService";
+import { getDocsAiApiBase } from "./docsAiConfig";
+import { getNonce, getScriptUri, getStyleUri } from "./webviewUtils";
+import type { DocsAiRecentConversation } from "./homescreenView";
+import { renderActionToolbar } from "./components/actionToolbar";
+
+type DocsAiMessage = {
+  command?: string;
+  action?: string;
+  eventName?: string;
+  payload?: AnalyticsPayload;
+  conversations?: DocsAiRecentConversation[];
+};
+
+export class DocsAiViewProvider implements vscode.WebviewViewProvider {
+  public static readonly viewType = "cloudinaryDocsAI";
+
+  private _view: vscode.WebviewView | undefined;
+  private _pendingPrompt: string | undefined;
+  private _pendingConversationId: string | undefined;
+  private readonly _recentConversationsStorageKey = "cloudinary.docsAiRecentConversations";
+
+  constructor(
+    private readonly _extensionUri: vscode.Uri,
+    private readonly _globalState: vscode.Memento,
+    private readonly _analytics: AnalyticsService | undefined,
+    private readonly _onRecentConversationsChange: (conversations: DocsAiRecentConversation[]) => void
+  ) {
+    const cached = this._globalState.get<DocsAiRecentConversation[]>(
+      this._recentConversationsStorageKey,
+      []
+    );
+    this._onRecentConversationsChange(cached);
+  }
+
+  resolveWebviewView(view: vscode.WebviewView): void {
+    this._view = view;
+    view.onDidDispose(() => {
+      this._view = undefined;
+    });
+
+    view.webview.options = {
+      enableScripts: true,
+      localResourceRoots: [vscode.Uri.joinPath(this._extensionUri, "media")],
+    };
+
+    view.webview.onDidReceiveMessage((message: DocsAiMessage) => {
+      if (message.command === "docsAiRecentConversations") {
+        this._handleRecentConversations(message.conversations);
+      } else if (message.command === "analyticsEvent") {
+        this._handleAnalyticsEvent(message);
+      } else if (message.command === "showHomescreen") {
+        vscode.commands.executeCommand("cloudinary.showHomescreen");
+      } else if (message.command === "runToolbar") {
+        this._handleToolbarAction(message.action);
+      }
+    });
+
+    const initialPrompt = this.consumePendingPrompt();
+    const initialConversationId = this.consumePendingConversationId();
+    this._analytics?.track("docs_ai_opened", {
+      entry_point: "webview_ready",
+      has_initial_prompt: !!initialPrompt,
+      has_initial_conversation: !!initialConversationId,
+    });
+    view.webview.html = this.getHtml(view.webview, initialPrompt, initialConversationId);
+  }
+
+  refresh(): void {
+    const view = this._view;
+    if (!view) {
+      return;
+    }
+    const initialPrompt = this.consumePendingPrompt();
+    const initialConversationId = this.consumePendingConversationId();
+    view.webview.html = this.getHtml(view.webview, initialPrompt, initialConversationId);
+  }
+
+  requestRecentConversations(): void {
+    this._view?.webview.postMessage({ command: "syncRecentConversations" });
+  }
+
+  queuePrompt(prompt: unknown): void {
+    const value = typeof prompt === "string" ? prompt.trim() : "";
+    if (!value) {
+      return;
+    }
+    this._pendingPrompt = value;
+    this._pendingConversationId = undefined;
+    this.flushPendingPrompt();
+  }
+
+  flushPendingPrompt(delay = 0): void {
+    const view = this._view;
+    if (!view || !this._pendingPrompt) {
+      return;
+    }
+
+    const postPrompt = () => {
+      if (!this._view || !this._pendingPrompt) {
+        return;
+      }
+      const prompt = this._pendingPrompt;
+      this._pendingPrompt = undefined;
+      this._view.webview.postMessage({ command: "askPrompt", prompt });
+    };
+
+    if (delay > 0) {
+      setTimeout(postPrompt, delay);
+      return;
+    }
+
+    postPrompt();
+  }
+
+  queueConversation(conversationId: unknown): void {
+    const value = typeof conversationId === "string" ? conversationId.trim() : "";
+    if (!value) {
+      return;
+    }
+    this._pendingPrompt = undefined;
+    this._pendingConversationId = value;
+    this.flushPendingConversation();
+  }
+
+  flushPendingConversation(delay = 0): void {
+    const view = this._view;
+    if (!view || !this._pendingConversationId) {
+      return;
+    }
+
+    const postConversation = () => {
+      if (!this._view || !this._pendingConversationId) {
+        return;
+      }
+      const conversationId = this._pendingConversationId;
+      this._pendingConversationId = undefined;
+      this._view.webview.postMessage({ command: "openConversation", conversationId });
+    };
+
+    if (delay > 0) {
+      setTimeout(postConversation, delay);
+      return;
+    }
+
+    postConversation();
+  }
+
+  private consumePendingPrompt(): string | undefined {
+    const prompt = this._pendingPrompt;
+    this._pendingPrompt = undefined;
+    return prompt;
+  }
+
+  private consumePendingConversationId(): string | undefined {
+    const conversationId = this._pendingConversationId;
+    this._pendingConversationId = undefined;
+    return conversationId;
+  }
+
+  private _handleRecentConversations(conversations: DocsAiRecentConversation[] | undefined): void {
+    if (!Array.isArray(conversations)) {
+      return;
+    }
+
+    const recent = conversations
+      .filter((conversation) => conversation.id && conversation.title)
+      .sort((a, b) => (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0));
+    void this._globalState.update(this._recentConversationsStorageKey, recent);
+    this._onRecentConversationsChange(recent);
+  }
+
+  private _handleAnalyticsEvent(message: DocsAiMessage): void {
+    if (!message.eventName) {
+      return;
+    }
+
+    this._analytics?.track(message.eventName, message.payload ?? {});
+  }
+
+  private getHtml(
+    webview: vscode.Webview,
+    initialPrompt?: string,
+    initialConversationId?: string
+  ): string {
+    const cssUri = getStyleUri(webview, this._extensionUri, "docs-ai.css");
+    const toolbarCssUri = getStyleUri(webview, this._extensionUri, "action-toolbar.css");
+    const scriptUri = getScriptUri(webview, this._extensionUri, "docs-ai.js");
+    const nonce = getNonce();
+    const appName = JSON.stringify(vscode.env.appName);
+    const initialPromptJson = JSON.stringify(initialPrompt ?? "");
+    const initialConversationIdJson = JSON.stringify(initialConversationId ?? "");
+    const apiBase = getDocsAiApiBase();
+    const apiBaseJson = JSON.stringify(apiBase);
+
+    const csp = [
+      "default-src 'none'",
+      `style-src ${webview.cspSource} 'unsafe-inline'`,
+      `script-src ${webview.cspSource} 'nonce-${nonce}'`,
+      `connect-src ${apiBase}`,
+      `img-src ${webview.cspSource} https: data:`,
+      `font-src ${webview.cspSource}`,
+    ].join("; ");
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="Content-Security-Policy" content="${csp}">
+  <link rel="stylesheet" href="${toolbarCssUri}">
+  <link rel="stylesheet" href="${cssUri}">
+  <title>Cloudinary Docs AI</title>
+</head>
+<body>
+  <div class="chat-shell">
+    <div class="header-wrapper">
+      ${renderActionToolbar({ id: "docs-ai-toolbar", ariaLabel: "Docs AI actions" })}
+      <div id="tab-bar" class="tab-bar">
+        <div class="tab-scroll"></div>
+        <div class="tab-actions">
+          <button id="new-chat-btn" class="tab-action-btn" title="New chat" aria-label="New chat">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
+          </button>
+          <button id="history-btn" class="tab-action-btn" title="Chat history" aria-label="Chat history">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+          </button>
+        </div>
+      </div>
+      <div id="history-dropdown" class="history-dropdown"></div>
+    </div>
+
+    <div id="conversation"></div>
+
+    <section class="composer">
+      <div class="input-row">
+        <textarea id="chat-input" rows="1" placeholder="Send a message..." autocomplete="off" dir="auto"></textarea>
+        <button id="send-btn" title="Send message" aria-label="Send message">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+        </button>
+        <button id="stop-btn" title="Stop generation" aria-label="Stop generation">
+          <svg width="14" height="14" viewBox="0 0 14 14"><rect x="2" y="2" width="10" height="10" rx="1.5" fill="currentColor"/></svg>
+        </button>
+      </div>
+      <p id="disclaimer">AI can make mistakes. Verify important info from <a href="https://cloudinary.com/documentation" target="_blank" rel="noopener noreferrer">Cloudinary docs</a>.</p>
+    </section>
+  </div>
+
+  <script nonce="${nonce}">
+    window.__IDE_NAME__ = ${appName};
+    window.__INITIAL_PROMPT__ = ${initialPromptJson};
+    window.__INITIAL_CONVERSATION_ID__ = ${initialConversationIdJson};
+    window.__DOCS_AI_API_BASE__ = ${apiBaseJson};
+  </script>
+  <script nonce="${nonce}" src="${scriptUri}"></script>
+</body>
+</html>`;
+  }
+
+  private _handleToolbarAction(action: string | undefined): void {
+    const commandMap: Record<string, string> = {
+      refresh: "cloudinary.docsAi.refresh",
+      openUploadWidget: "cloudinary.openUploadWidget",
+      showHomescreen: "cloudinary.showHomescreen",
+      openGlobalConfig: "cloudinary.openGlobalConfig",
+    };
+    const command = action ? commandMap[action] : undefined;
+    if (command) {
+      vscode.commands.executeCommand(command);
+    }
+  }
+}
diff --git a/src/webview/homescreenView.ts b/src/webview/homescreenView.ts
index ede5d43..89c41b8 100644
--- a/src/webview/homescreenView.ts
+++ b/src/webview/homescreenView.ts
@@ -4,16 +4,23 @@
  */
 
 import * as vscode from "vscode";
-import { CloudinaryTreeDataProvider } from "../tree/treeDataProvider";
+import { AnalyticsService } from "../analytics/analyticsService";
+import { CloudinaryService } from "../cloudinary/cloudinaryService";
 import { createWebviewDocument, getScriptUri, getStyleUri } from "./webviewUtils";
+import type { LibraryWebviewViewProvider } from "./libraryView";
 import { loadEnvironments } from "../config/configUtils";
+import { getConnectionStatus } from "../config/connectionStatus";
+import { buildAiToolsNextStepsMessage } from "../utils/aiToolsGuidance";
 import skillsConfig from "../utils/skills-config.json";
+import { actionIcons } from "./icons";
 import {
   PlatformEntry,
   Scope,
   SkillInfo,
   MCP_SERVERS,
   detectEditor,
+  getMcpRootKey,
+  getEditorDisplayName,
   getMcpFilePath,
   fetchSkillList,
   fetchSkillContent,
@@ -26,18 +33,32 @@ import {
   getPlatformCovers,
 } from "../aiToolsService";
 
+export interface DocsAiRecentConversation {
+  id: string;
+  title: string;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+const DOCS_AI_RECENT_CONVERSATIONS_STORAGE_KEY = "cloudinary.docsAiRecentConversations";
+
 export class HomescreenViewProvider implements vscode.WebviewViewProvider {
   public static readonly viewType = "cloudinaryHomescreen";
 
   constructor(
     private readonly _extensionUri: vscode.Uri,
-    private readonly _provider: CloudinaryTreeDataProvider
-  ) {}
+    private readonly _service: CloudinaryService,
+    private readonly _globalState: vscode.Memento,
+    private readonly _libraryWebview?: LibraryWebviewViewProvider,
+    private readonly _analytics?: AnalyticsService
+  ) { }
 
   private _webviewView: vscode.WebviewView | undefined;
   private _cachedSkills: SkillInfo[] | undefined;
   private _currentPlatform: string = "claude-code";
   private _currentScope: Scope = "project";
+  private _docsAiRecentConversations: DocsAiRecentConversation[] = [];
+  private _requestDocsAiRecentConversations: (() => void) | undefined;
 
   async resolveWebviewView(
     webviewView: vscode.WebviewView,
@@ -52,7 +73,10 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
 
     webviewView.webview.options = {
       enableScripts: true,
-      localResourceRoots: [vscode.Uri.joinPath(this._extensionUri, "media")],
+      localResourceRoots: [
+        vscode.Uri.joinPath(this._extensionUri, "media"),
+        vscode.Uri.joinPath(this._extensionUri, "resources"),
+      ],
     };
 
     const scriptUri = getScriptUri(
@@ -65,12 +89,15 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
       this._extensionUri,
       "homescreen.css"
     );
+    const logoUri = webviewView.webview.asWebviewUri(
+      vscode.Uri.joinPath(this._extensionUri, "resources", "cloudinary_icon_blue.png")
+    );
 
     webviewView.webview.html = createWebviewDocument({
       title: "Cloudinary",
       webview: webviewView.webview,
       extensionUri: this._extensionUri,
-      bodyContent: this._getBodyContent(),
+      bodyContent: this._getBodyContent(logoUri),
       additionalStyles: [homescreenCssUri],
       additionalScripts: [scriptUri],
     });
@@ -86,14 +113,33 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
       }) => {
         switch (message.command) {
           case "ready":
+            this._analytics?.track("home_opened", { entry_point: "webview_ready" });
             await this._sendHomescreenData();
             break;
+          case "refreshDocsAiRecentConversations":
+            this._requestDocsAiRecentConversations?.();
+            if (this._docsAiRecentConversations.length > 0) {
+              this._sendDocsAiRecentConversations();
+            }
+            break;
+          case "clearDocsAiConversations":
+            this._docsAiRecentConversations = [];
+            await this._globalState.update(DOCS_AI_RECENT_CONVERSATIONS_STORAGE_KEY, []);
+            this._sendDocsAiRecentConversations();
+            break;
           case "openGlobalConfig":
+            this._analytics?.track("config_opened", { entry_point: "homescreen" });
             vscode.commands.executeCommand("cloudinary.openGlobalConfig");
             break;
           case "showLibrary":
             vscode.commands.executeCommand("cloudinary.showLibrary");
             break;
+          case "showDocsAI":
+            vscode.commands.executeCommand("cloudinary.showDocsAI", message.data);
+            break;
+          case "showDocsAIConversation":
+            vscode.commands.executeCommand("cloudinary.showDocsAIConversation", message.data);
+            break;
           case "openUploadWidget":
             vscode.commands.executeCommand("cloudinary.openUploadWidget");
             break;
@@ -102,21 +148,31 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
             break;
           case "searchAssets":
             if (message.data?.trim()) {
-              this._provider.refresh({ searchQuery: message.data.trim() });
-              vscode.commands.executeCommand("cloudinary.showLibrary");
+              const query = message.data.trim();
+              this._analytics?.track("asset_search", {
+                entry_point: "homescreen",
+                query_length: query.length,
+              });
+              await vscode.commands.executeCommand("cloudinary.showLibrary", query);
             }
             break;
           case "clearSearch":
-            this._provider.refresh({ searchQuery: null });
+            await this._libraryWebview?.setSearch(null);
             break;
           case "switchEnvironment":
             vscode.commands.executeCommand("cloudinary.switchEnvironment");
             break;
           case "aiToolsExpanded":
+            // First open: auto-detect the user's editor as the default platform.
             this._currentPlatform = detectEditorPlatform();
             this._currentScope = "project";
             await this._handleAiToolsExpanded();
             break;
+          case "aiToolsRefresh":
+            // Re-render after an install (or other in-place refresh) WITHOUT
+            // resetting the user's chosen platform/scope back to auto-detected.
+            await this._handleAiToolsExpanded();
+            break;
           case "changePlatform":
             if (message.platform) {
               this._currentPlatform = message.platform;
@@ -152,41 +208,82 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
     vscode.commands.executeCommand("workbench.view.extension.cloudinary");
     // Post focusSearch after the view has had time to become visible
     setTimeout(() => {
-      this._webviewView?.webview.postMessage({ command: "focusSearch" });
+      this._safePost({ command: "focusSearch" });
     }, 250);
   }
 
+  private _safePost(message: unknown): void {
+    const targetView = this._webviewView;
+    if (!targetView) {
+      return;
+    }
+    try {
+      targetView.webview.postMessage(message);
+    } catch {
+      // Webview disposed between checks; safe to drop.
+    }
+  }
+
   async refresh(): Promise<void> {
     await this._sendHomescreenData();
   }
 
+  setDocsAiRecentConversations(conversations: DocsAiRecentConversation[]): void {
+    this._docsAiRecentConversations = conversations
+      .filter((conversation) => conversation.id && conversation.title)
+      .sort((a, b) => (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0));
+    this._sendDocsAiRecentConversations();
+  }
+
+  setDocsAiRecentConversationsRefresh(handler: () => void): void {
+    this._requestDocsAiRecentConversations = handler;
+  }
+
   private async _sendHomescreenData(): Promise<void> {
     const view = this._webviewView;
     if (!view) { return; }
 
-    const hasConfig = !!(this._provider.cloudName && this._provider.apiKey);
-    const cloudName = this._provider.cloudName || "";
-    const folderMode = this._provider.dynamicFolders ? "Dynamic folders" : "Fixed folders";
-
-    let envCount = hasConfig ? 1 : 0;
+    let envCount = 0;
     try {
       const envs = await loadEnvironments();
       envCount = Object.keys(envs).length;
     } catch { /* use default */ }
 
-    view.webview.postMessage({ command: "homescreenData", hasConfig, cloudName, folderMode, envCount });
+    // Compute the status AFTER the await above and read it right before posting,
+    // so a send that started while validation was still in flight reflects the
+    // latest credentialsValid (avoids a stale "checking"/"connected" post racing
+    // ahead of the post-validation refresh). See getConnectionStatus().
+    const status = getConnectionStatus({
+      cloudName: this._service.cloudName,
+      apiKey: this._service.apiKey,
+      apiSecret: this._service.apiSecret,
+      credentialsValid: this._service.credentialsValid,
+    });
+    const cloudName = this._service.cloudName || "";
+    const folderMode = this._service.dynamicFolders ? "Dynamic folders" : "Fixed folders";
+
+    this._safePost({ command: "homescreenData", status, cloudName, folderMode, envCount });
+    this._sendDocsAiRecentConversations();
+    this._requestDocsAiRecentConversations?.();
+  }
+
+  private _sendDocsAiRecentConversations(): void {
+    this._safePost({
+      command: "docsAiRecentConversations",
+      conversations: this._docsAiRecentConversations,
+    });
   }
 
-  private _getBodyContent(): string {
+  private _getBodyContent(logoUri: vscode.Uri): string {
     return `
 
       <div class="hs-root">
         <div class="hs-header">
           <div class="hs-brand">
             <div class="hs-brand-left">
-              <svg class="hs-brand-icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
-                <path d="M19.5 9.5a6.5 6.5 0 0 0-12.47-2A5 5 0 0 0 7 17.5h12a4.5 4.5 0 0 0 .5-8.97z" fill="rgba(255,255,255,0.9)" stroke="rgba(255,255,255,0.2)" stroke-width="0.5"/>
-              </svg>
+              <span class="hs-brand-logo-wrap" aria-hidden="true">
+                <img class="hs-brand-logo" src="${logoUri}" alt="" />
+              </span>
               <span class="hs-brand-name">Cloudinary</span>
             </div>
             <span class="hs-status-pill">
@@ -206,7 +303,7 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
         </div>
 
         <div id="hs-setup-banner" class="hs-setup-banner hidden">
-          <span class="hs-setup-banner-icon">⚠</span>
+          <span class="hs-setup-banner-icon" aria-hidden="true">${actionIcons.warning("sm")}</span>
           <span class="hs-setup-banner-text">Add your API credentials to connect</span>
           <button id="hs-btn-configure" class="hs-setup-banner-btn" data-command="openGlobalConfig">Configure</button>
         </div>
@@ -226,6 +323,9 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
               spellcheck="false"
               aria-label="Search media library"
             />
+            <span id="hs-search-loading" class="hs-search-loading hidden" role="status" aria-label="Searching library">
+              <span class="hs-search-spinner" aria-hidden="true"></span>
+            </span>
             <button id="hs-search-clear" class="hs-search-clear hidden" title="Clear search" aria-label="Clear search">✕</button>
           </div>
         </div>
@@ -336,6 +436,43 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
             </div>
 
           </div><!-- /hs-ai-panel -->
+
+          <section class="hs-docs-ai-home" aria-labelledby="hs-docs-ai-heading">
+            <div class="hs-docs-ai-empty">
+              <h2 id="hs-docs-ai-heading" class="hs-docs-ai-empty-heading">Ask Cloudinary AI</h2>
+              <p class="hs-docs-ai-empty-sub">Ask me anything about our products and documentation.</p>
+              <div class="hs-docs-ai-empty-input-row">
+                <textarea
+                  id="hs-docs-ai-input"
+                  class="hs-docs-ai-empty-input"
+                  rows="1"
+                  placeholder="Send a message..."
+                  autocomplete="off"
+                  dir="auto"
+                  spellcheck="true"
+                  aria-label="Ask Cloudinary AI"
+                ></textarea>
+                <button id="hs-docs-ai-submit" class="hs-docs-ai-empty-send-btn" type="button" title="Send message" aria-label="Send message" disabled>
+                  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+                </button>
+              </div>
+              <div class="hs-docs-ai-chips" aria-label="Suggested documentation questions">
+                <button class="hs-docs-ai-chip" type="button" data-question="What's new in Cloudinary?">What's new in Cloudinary?</button>
+                <button class="hs-docs-ai-chip" type="button" data-question="How do I upload images?">How do I upload images?</button>
+                <button class="hs-docs-ai-chip" type="button" data-question="Explain image transformations">Explain image transformations</button>
+                <button class="hs-docs-ai-chip" type="button" data-question="What SDKs does Cloudinary support?">What SDKs does Cloudinary support?</button>
+              </div>
+              <div class="hs-docs-ai-history-toggle-wrap">
+                <button id="hs-docs-ai-history-toggle" class="hs-docs-ai-history-toggle hidden" type="button" title="View recent conversations" aria-label="View recent conversations" aria-expanded="false">
+                  <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg>
+                  <span class="hs-docs-ai-history-toggle-label">View recent conversations</span>
+                </button>
+              </div>
+              <div id="hs-docs-ai-recent" class="hs-docs-ai-history-panel hidden" aria-label="Conversation history">
+                <div id="hs-docs-ai-recent-list" class="hs-docs-ai-recent-list"></div>
+              </div>
+            </div>
+          </section>
         </div>
 
         <div class="hs-footer">
@@ -354,7 +491,7 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
 
     const workspaceFolders = vscode.workspace.workspaceFolders;
     if (!workspaceFolders || workspaceFolders.length === 0) {
-      view.webview.postMessage({ command: "aiToolsData", error: "Please open a workspace folder first." });
+      this._safePost({ command: "aiToolsData", error: "Please open a workspace folder first." });
       return;
     }
     const rootUri = workspaceFolders[0].uri;
@@ -367,27 +504,25 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
 
       const platform = getPlatformEntry(this._currentPlatform);
       if (!platform) {
-        view.webview.postMessage({ command: "aiToolsData", error: `Unknown platform: ${this._currentPlatform}` });
+        this._safePost({ command: "aiToolsData", error: `Unknown platform: ${this._currentPlatform}` });
         return;
       }
 
-      const { project, global: globalSet } = await readInstalledSkillDirNames(rootUri, platform, skills);
-      const inScope = this._currentScope === "project" ? project   : globalSet;
-      const inOther = this._currentScope === "project" ? globalSet : project;
-
       const covers = getPlatformCovers(platform, this._currentScope);
 
       const editor = detectEditor();
       const mcpFilePath = getMcpFilePath(editor);
-      const rootKey = editor === "vscode" ? "servers" : "mcpServers";
-      const configuredMcpSet = await readConfiguredMcpServerKeys(rootUri, mcpFilePath, rootKey);
 
-      const editorLabels: Record<string, string> = {
-        vscode: "VS Code", cursor: "Cursor", windsurf: "Windsurf", antigravity: "Antigravity",
-      };
-      const mcpEditorLabel = editorLabels[editor];
+      const [{ project, global: globalSet }, configuredMcpSet] = await Promise.all([
+        readInstalledSkillDirNames(rootUri, platform, skills),
+        readConfiguredMcpServerKeys(rootUri, mcpFilePath, getMcpRootKey(editor)),
+      ]);
+      const inScope = this._currentScope === "project" ? project : globalSet;
+      const inOther = this._currentScope === "project" ? globalSet : project;
+
+      const mcpEditorLabel = getEditorDisplayName(editor);
 
-      view.webview.postMessage({
+      this._safePost({
         command: "aiToolsData",
         platform: this._currentPlatform,
         scope: this._currentScope,
@@ -410,7 +545,7 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
         mcpEditorLabel,
       });
     } catch (err: any) {
-      view.webview.postMessage({ command: "aiToolsData", error: err.message ?? String(err) });
+      this._safePost({ command: "aiToolsData", error: err.message ?? String(err) });
     }
   }
 
@@ -425,16 +560,18 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
 
     const workspaceFolders = vscode.workspace.workspaceFolders;
     if (!workspaceFolders || workspaceFolders.length === 0) {
-      view.webview.postMessage({ command: "aiToolsResult", errors: ["No workspace folder open."] });
+      this._safePost({ command: "aiToolsResult", errors: ["No workspace folder open."] });
       return;
     }
     const rootUri = workspaceFolders[0].uri;
     const errors: string[] = [];
+    let installedSkillsCount = 0;
+    const installedMcp: string[] = [];
     const cachedSkills = this._cachedSkills ?? [];
     const platform = getPlatformEntry(platformId);
 
     if (!platform) {
-      view.webview.postMessage({ command: "aiToolsResult", errors: [`Unknown platform: ${platformId}`] });
+      this._safePost({ command: "aiToolsResult", errors: [`Unknown platform: ${platformId}`] });
       return;
     }
 
@@ -447,7 +584,7 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
         content = await fetchSkillContent(dirName);
       } catch (err: any) {
         errors.push(`${dirName}: ${err.message}`);
-        view.webview.postMessage({ command: "aiToolsProgress", item: dirName, status: "error" });
+        this._safePost({ command: "aiToolsProgress", item: dirName, status: "error" });
         continue;
       }
 
@@ -458,31 +595,55 @@ export class HomescreenViewProvider implements vscode.WebviewViewProvider {
       } catch (err: any) {
         errors.push(`${dirName}: ${err.message}`);
       }
-      view.webview.postMessage({
+      const skillOk = errors.length === errsBefore;
+      if (skillOk) { installedSkillsCount++; }
+      this._safePost({
         command: "aiToolsProgress",
         item: dirName,
-        status: errors.length > errsBefore ? "error" : "done",
+        status: skillOk ? "done" : "error",
       });
     }
 
+    let mcpEditorLabel: string | undefined;
     if (mcpServers.length > 0) {
       const editor = detectEditor();
+      mcpEditorLabel = getEditorDisplayName(editor);
       const createdFiles: string[] = [];
       try {
         await installMcpServers(rootUri, editor, mcpServers, createdFiles);
         for (const key of mcpServers) {
-          view.webview.postMessage({ command: "aiToolsProgress", item: key, status: "done" });
+          this._safePost({ command: "aiToolsProgress", item: key, status: "done" });
+          installedMcp.push(key);
         }
       } catch (err: any) {
         errors.push(`MCP: ${err.message}`);
         for (const key of mcpServers) {
-          view.webview.postMessage({ command: "aiToolsProgress", item: key, status: "error" });
+          this._safePost({ command: "aiToolsProgress", item: key, status: "error" });
         }
       }
     }
 
-    this._cachedSkills = undefined;
-    view.webview.postMessage({ command: "aiToolsResult", errors });
+    this._safePost({ command: "aiToolsResult", errors });
+    this._showAiToolsNextSteps(installedSkillsCount, installedMcp, mcpEditorLabel);
   }
-}
 
+  /**
+   * Surfaces post-install guidance. MCP servers in particular only take effect
+   * after the editor reloads, and users otherwise see them as "configured" but
+   * not connected, so we spell out the restart/verify step explicitly.
+   */
+  private _showAiToolsNextSteps(
+    installedSkillsCount: number,
+    installedMcp: string[],
+    mcpEditorLabel?: string
+  ): void {
+    const message = buildAiToolsNextStepsMessage(
+      installedSkillsCount,
+      installedMcp.length,
+      mcpEditorLabel
+    );
+    if (message) {
+      vscode.window.showInformationMessage(message);
+    }
+  }
+}
diff --git a/src/webview/icons.ts b/src/webview/icons.ts
index ba3f09a..09d3cfc 100644
--- a/src/webview/icons.ts
+++ b/src/webview/icons.ts
@@ -125,6 +125,24 @@ export const actionIcons = {
       `<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z"/>`,
       size
     ),
+
+  lock: (size: IconSize = "md") =>
+    wrapSvg(
+      `<path d="M17 10h-1V7c0-2.21-1.79-4-4-4S8 4.79 8 7v3H7c-1.1 0-2 .9-2 2v8c0 1.1.9 2 2 2h10c1.1 0 2-.9 2-2v-8c0-1.1-.9-2-2-2zm-7-3c0-1.1.9-2 2-2s2 .9 2 2v3h-4V7zm7 13H7v-8h10v8z"/>`,
+      size
+    ),
+
+  home: (size: IconSize = "md") =>
+    wrapSvg(
+      `<path d="M12 3L2 12h3v8h6v-6h2v6h6v-8h3L12 3z"/>`,
+      size
+    ),
+
+  tune: (size: IconSize = "md") =>
+    wrapSvg(
+      `<path d="M4 6h8v2H4V6zm10 0h6v2h-6V6zm-4 5h10v2H10v-2zM4 11h4v2H4v-2zm12 5h4v2h-4v-2zM4 16h10v2H4v-2z"/><circle cx="13" cy="7" r="2"/><circle cx="9" cy="12" r="2"/><circle cx="15" cy="17" r="2"/>`,
+      size
+    ),
 };
 
 /**
diff --git a/src/webview/libraryView.ts b/src/webview/libraryView.ts
new file mode 100644
index 0000000..848a102
--- /dev/null
+++ b/src/webview/libraryView.ts
@@ -0,0 +1,499 @@
+import * as vscode from 'vscode';
+import { AnalyticsService } from '../analytics/analyticsService';
+import { isPlaceholderConfig } from '../config/configUtils';
+import { CloudinaryService } from '../cloudinary/cloudinaryService';
+import {
+  ChildrenPage,
+  ClientAsset,
+  ResourceTypeFilter,
+  SortDirection,
+} from '../cloudinary/types';
+import { handleCloudinaryError } from '../utils/cloudinaryErrorHandler';
+import {
+  createWebviewDocument,
+  getScriptUri,
+  getStyleUri,
+} from './webviewUtils';
+import { escapeHtml } from './utils/helpers';
+import { renderActionToolbar } from './components/actionToolbar';
+
+export class LibraryWebviewViewProvider implements vscode.WebviewViewProvider {
+  public static readonly viewType = 'cloudinaryMediaLibrary';
+
+  private _view: vscode.WebviewView | undefined;
+  private _viewState = {
+    folderPath: '',
+    searchQuery: null as string | null,
+    resourceTypeFilter: 'all' as ResourceTypeFilter,
+    sortDirection: 'desc' as SortDirection,
+  };
+  private _cache = new Map<string, ChildrenPage>();
+  private _prefetchingFolders = new Set<string>();
+
+  constructor(
+    private readonly _extensionUri: vscode.Uri,
+    private readonly _service: CloudinaryService,
+    private readonly _analytics?: AnalyticsService,
+  ) {}
+
+  resolveWebviewView(view: vscode.WebviewView): void {
+    this._view = view;
+    view.onDidDispose(() => {
+      this._view = undefined;
+    });
+
+    view.webview.options = {
+      enableScripts: true,
+      localResourceRoots: [
+        vscode.Uri.joinPath(this._extensionUri, 'media'),
+        vscode.Uri.joinPath(this._extensionUri, 'resources'),
+      ],
+    };
+
+    const scriptUri = getScriptUri(view.webview, this._extensionUri, 'library.js');
+    const cssUri = getStyleUri(view.webview, this._extensionUri, 'library.css');
+    const toolbarCssUri = getStyleUri(view.webview, this._extensionUri, 'action-toolbar.css');
+
+    const sel = (current: string, value: string): string =>
+      current === value ? ' selected' : '';
+    const rt = this._viewState.resourceTypeFilter;
+    const sd = this._viewState.sortDirection;
+    const searchValue = this._viewState.searchQuery || '';
+
+    view.webview.html = createWebviewDocument({
+      title: 'Cloudinary Media Library',
+      webview: view.webview,
+      extensionUri: this._extensionUri,
+      bodyContent: `
+        <header class="lib-header">
+          ${renderActionToolbar({ id: 'lib-toolbar', ariaLabel: 'Library actions' })}
+          <div id="lib-filter" class="lib-filter" role="group" aria-label="Filter and sort">
+            <label class="lib-filter__group">
+              <span class="lib-filter__label">Type</span>
+              <select id="lib-filter-type" class="lib-filter__select" aria-label="Filter by resource type">
+                <option value="all"${sel(rt, 'all')}>All</option>
+                <option value="image"${sel(rt, 'image')}>Images</option>
+                <option value="video"${sel(rt, 'video')}>Videos</option>
+                <option value="raw"${sel(rt, 'raw')}>Raw</option>
+              </select>
+            </label>
+            <label class="lib-filter__group">
+              <span class="lib-filter__label">Sort</span>
+              <select id="lib-filter-sort" class="lib-filter__select" aria-label="Sort direction">
+                <option value="desc"${sel(sd, 'desc')}>Newest</option>
+                <option value="asc"${sel(sd, 'asc')}>Oldest</option>
+              </select>
+            </label>
+          </div>
+          <div id="lib-search" class="lib-search" role="search" aria-label="Search media library">
+            <div class="lib-search__wrap">
+              <svg class="lib-search__icon" width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+                <path d="M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001q.044.06.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1 1 0 0 0-.115-.099zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0"/>
+              </svg>
+              <input
+                id="lib-search-input"
+                class="lib-search__input"
+                type="text"
+                placeholder="Search library…"
+                value="${escapeHtml(searchValue)}"
+                autocomplete="off"
+                spellcheck="false"
+                aria-label="Search media library"
+              />
+              <span id="lib-search-loading" class="lib-search__loading hidden" role="status" aria-label="Searching library">
+                <span class="lib-search__spinner" aria-hidden="true"></span>
+              </span>
+              <button id="lib-search-clear" class="lib-search__clear hidden" title="Clear search" aria-label="Clear search">✕</button>
+            </div>
+          </div>
+        </header>
+        <div id="lib-root" class="lib-root" role="tree" aria-label="Media library"></div>
+      `,
+      additionalStyles: [toolbarCssUri, cssUri],
+      additionalScripts: [scriptUri],
+    });
+
+    view.webview.onDidReceiveMessage((message) => {
+      void this.handleMessage(message);
+    });
+  }
+
+  private async handleMessage(message: any): Promise<void> {
+    switch (message?.command) {
+      case 'ready':
+        this._analytics?.track('library_opened', { entry_point: 'webview_ready' });
+        this.post({
+          command: 'envChanged',
+          cloudName: this._service.cloudName || '',
+          folderMode: this._service.dynamicFolders ? 'dynamic' : 'fixed',
+          hasConfig: this.hasCredentials(),
+        });
+        this.post({
+          command: 'viewStateChanged',
+          resourceTypeFilter: this._viewState.resourceTypeFilter,
+          sortDirection: this._viewState.sortDirection,
+        });
+        if (this._viewState.searchQuery) {
+          this.post({ command: 'searchPending', query: this._viewState.searchQuery });
+        }
+        await this.refreshCurrentView();
+        return;
+      case 'expandFolder':
+        await this.sendFolder(String(message.path || ''));
+        return;
+      case 'openAsset':
+        if (message.asset) {
+          const asset = message.asset as ClientAsset;
+          this._analytics?.track('asset_opened', {
+            entry_point: 'library',
+            resource_type: asset.resource_type,
+            asset_type: asset.type,
+          });
+          const filename =
+            asset.display_name ||
+            asset.public_id.split('/').pop() ||
+            asset.public_id;
+          void vscode.commands.executeCommand('cloudinary.openAsset', {
+            ...asset,
+            displayType: asset.resource_type,
+            filename,
+          });
+        }
+        return;
+      case 'runToolbar': {
+        const action = String(message.action || '');
+        const commandMap: Record<string, string> = {
+          refresh: 'cloudinary.refresh',
+          openUploadWidget: 'cloudinary.openUploadWidget',
+          showHomescreen: 'cloudinary.showHomescreen',
+          openGlobalConfig: 'cloudinary.openGlobalConfig',
+        };
+        const command = commandMap[action];
+        if (command) {
+          void vscode.commands.executeCommand(command);
+        }
+        return;
+      }
+      case 'contextAction': {
+        const action = String(message.action || '');
+        if (
+          action === 'copyUrl' ||
+          action === 'copyPublicId' ||
+          action === 'copyOptimizedUrl'
+        ) {
+          void vscode.commands.executeCommand(`cloudinary.${action}`, {
+            data: message.data,
+          });
+        } else if (action === 'uploadToFolder') {
+          this._analytics?.track('upload_widget_opened', {
+            entry_point: 'library_context',
+            folder_selected: true,
+          });
+          void vscode.commands.executeCommand('cloudinary.uploadToFolder', {
+            label: message.data?.name || '',
+            data: message.data,
+          });
+        }
+        return;
+      }
+      case 'clearSearch':
+        await this.setSearch(null);
+        return;
+      case 'searchAssets': {
+        const query = typeof message.query === 'string' ? message.query : '';
+        await this.setSearch(query);
+        return;
+      }
+      case 'setView': {
+        await this.applyView({
+          resourceTypeFilter: message.resourceTypeFilter,
+          sortDirection: message.sortDirection,
+        });
+        return;
+      }
+      default:
+        return;
+    }
+  }
+
+  async setSearch(query: string | null): Promise<void> {
+    this._viewState.searchQuery = query && query.trim().length > 0
+      ? query.trim()
+      : null;
+    if (this._viewState.searchQuery) {
+      this._analytics?.track('asset_search', {
+        entry_point: 'library',
+        query_length: this._viewState.searchQuery.length,
+        resource_type: this._viewState.resourceTypeFilter,
+      });
+    }
+
+    if (!this._view) {
+      return;
+    }
+
+    if (this._viewState.searchQuery) {
+      this.post({ command: 'searchPending', query: this._viewState.searchQuery });
+    }
+    try {
+      await this.refreshCurrentView();
+    } catch (err: any) {
+      handleCloudinaryError('Failed to search library', err);
+      this.post({
+        command: 'error',
+        message: err?.message || 'Failed to search library',
+      });
+    }
+  }
+
+  async applyView(opts: {
+    resourceTypeFilter?: ResourceTypeFilter;
+    sortDirection?: SortDirection;
+  }): Promise<void> {
+    if (opts.resourceTypeFilter) {
+      this._viewState.resourceTypeFilter = opts.resourceTypeFilter;
+    }
+    if (opts.sortDirection) {
+      this._viewState.sortDirection = opts.sortDirection;
+    }
+
+    this._cache.clear();
+    this._analytics?.track('library_view_changed', {
+      resource_type: this._viewState.resourceTypeFilter,
+      sort_direction: this._viewState.sortDirection,
+    });
+    this.post({
+      command: 'viewStateChanged',
+      resourceTypeFilter: this._viewState.resourceTypeFilter,
+      sortDirection: this._viewState.sortDirection,
+    });
+
+    try {
+      await this.refreshCurrentView();
+    } catch (err: any) {
+      handleCloudinaryError('Failed to apply library view options', err);
+      this.post({
+        command: 'error',
+        message: err?.message || 'Failed to refresh library view',
+      });
+    }
+  }
+
+  async refresh(): Promise<void> {
+    this._cache.clear();
+    try {
+      await this.refreshCurrentView();
+    } catch (err: any) {
+      handleCloudinaryError('Failed to refresh library', err);
+      this.post({
+        command: 'error',
+        message: err?.message || 'Failed to refresh library',
+      });
+    }
+  }
+
+  async envChanged(): Promise<void> {
+    this._cache.clear();
+    this._viewState = {
+      folderPath: '',
+      searchQuery: null,
+      resourceTypeFilter: 'all',
+      sortDirection: 'desc',
+    };
+    this.post({
+      command: 'envChanged',
+      cloudName: this._service.cloudName || '',
+      folderMode: this._service.dynamicFolders ? 'dynamic' : 'fixed',
+      hasConfig: this.hasCredentials(),
+    });
+    this.post({
+      command: 'viewStateChanged',
+      resourceTypeFilter: this._viewState.resourceTypeFilter,
+      sortDirection: this._viewState.sortDirection,
+    });
+    await this.sendRoot();
+  }
+
+  private async sendRoot(): Promise<void> {
+    if (!this.hasCredentials()) {
+      return;
+    }
+
+    const page = await this.loadFolder('');
+    this.post({
+      command: 'rootData',
+      folders: page.folders,
+      assets: page.assets,
+      hasMore: !!page.nextCursor,
+    });
+
+    if (page.nextCursor) {
+      this.startPrefetch('', page.nextCursor);
+    }
+  }
+
+  private async sendSearch(query: string): Promise<void> {
+    if (!this.hasCredentials()) {
+      return;
+    }
+
+    try {
+      const result = await this._service.searchAssets(query, {
+        resourceTypeFilter: this._viewState.resourceTypeFilter,
+        sortDirection: this._viewState.sortDirection,
+      });
+
+      this.post({
+        command: 'searchData',
+        query,
+        assets: result.assets,
+        hasMore: !!result.nextCursor,
+      });
+
+      if (result.nextCursor) {
+        this.startSearchPrefetch(query, result.nextCursor);
+      }
+    } catch (err: any) {
+      handleCloudinaryError('Failed to search library', err);
+      this.post({
+        command: 'error',
+        message: err?.message || 'Failed to search library',
+      });
+    }
+  }
+
+  private async sendFolder(path: string): Promise<void> {
+    if (!this.hasCredentials()) {
+      return;
+    }
+
+    const page = await this.loadFolder(path);
+    this.post({
+      command: 'folderData',
+      path,
+      folders: page.folders,
+      assets: page.assets,
+      hasMore: !!page.nextCursor,
+    });
+
+    if (page.nextCursor) {
+      this.startPrefetch(path, page.nextCursor);
+    }
+  }
+
+  private hasCredentials(): boolean {
+    const service = this._service;
+    if (!service.cloudName || !service.apiKey || !service.apiSecret) {
+      return false;
+    }
+
+    if (isPlaceholderConfig(service.cloudName, service.apiKey, service.apiSecret)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  private async loadFolder(path: string): Promise<ChildrenPage> {
+    const cached = this._cache.get(path);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const page = await this._service.fetchChildren(path, {
+        resourceTypeFilter: this._viewState.resourceTypeFilter,
+        sortDirection: this._viewState.sortDirection,
+      });
+      this._cache.set(path, page);
+      return page;
+    } catch (err: any) {
+      handleCloudinaryError('Failed to fetch folders or assets', err);
+      this.post({
+        command: 'error',
+        message: err?.message || 'Failed to load library',
+      });
+      return { folders: [], assets: [], nextCursor: null };
+    }
+  }
+
+  private async refreshCurrentView(): Promise<void> {
+    if (this._viewState.searchQuery) {
+      await this.sendSearch(this._viewState.searchQuery);
+      return;
+    }
+
+    await this.sendRoot();
+  }
+
+  private startPrefetch(path: string, startCursor: string): void {
+    if (this._prefetchingFolders.has(path)) {
+      return;
+    }
+
+    this._prefetchingFolders.add(path);
+
+    this._service.prefetchRemaining(
+      path,
+      startCursor,
+      {
+        resourceTypeFilter: this._viewState.resourceTypeFilter,
+        sortDirection: this._viewState.sortDirection,
+      },
+      (assets, hasMore) => {
+        const entry = this._cache.get(path);
+        if (entry) {
+          entry.assets = entry.assets.concat(assets);
+          entry.nextCursor = hasMore ? entry.nextCursor : null;
+        }
+
+        this.post({ command: 'assetsAppended', path, assets, hasMore });
+      }
+    )
+      .catch((err) => {
+        console.error('Prefetch error:', err);
+      })
+      .finally(() => {
+        this._prefetchingFolders.delete(path);
+      });
+  }
+
+  private startSearchPrefetch(query: string, startCursor: string): void {
+    const key = `search:${query}`;
+    if (this._prefetchingFolders.has(key)) {
+      return;
+    }
+
+    this._prefetchingFolders.add(key);
+
+    this._service.prefetchSearchResults(
+      query,
+      startCursor,
+      {
+        resourceTypeFilter: this._viewState.resourceTypeFilter,
+        sortDirection: this._viewState.sortDirection,
+      },
+      (assets, hasMore) => {
+        this.post({ command: 'searchAppended', assets, hasMore });
+      }
+    )
+      .catch((err) => {
+        console.error(err);
+      })
+      .finally(() => {
+        this._prefetchingFolders.delete(key);
+      });
+  }
+
+  private post(message: unknown): void {
+    const view = this._view;
+    if (!view) {
+      return;
+    }
+    try {
+      view.webview.postMessage(message);
+    } catch {
+      // Webview disposed between checks; safe to drop.
+    }
+  }
+}
diff --git a/src/webview/scripts/welcomeScreen.ts b/src/webview/scripts/welcomeScreen.ts
index 30994c2..bb3b40c 100644
--- a/src/webview/scripts/welcomeScreen.ts
+++ b/src/webview/scripts/welcomeScreen.ts
@@ -16,8 +16,8 @@ export function getWelcomeScreenScript(): string {
       vscode.postMessage({ command: 'openExternal', data: url });
     }
 
-    function focusTreeView() {
-      vscode.postMessage({ command: 'focusTreeView' });
+    function focusDashboard() {
+      vscode.postMessage({ command: 'focusDashboard' });
     }
 
     function getConfigExample() {
diff --git a/test/e2e/README.md b/test/e2e/README.md
index 5143f58..bc83225 100644
--- a/test/e2e/README.md
+++ b/test/e2e/README.md
@@ -11,7 +11,7 @@ pnpm install
 
 ## Environment variables
 
-End-to-end runs require Cloudinary credentials in `process.env`. The `onPrepare` hook in `wdio.conf.ts` reads `E2E_CLOUD`, `E2E_API_KEY`, and `E2E_API_SECRET`, then writes `~/.cloudinary/environments.json` in the shape the extension expects (cloud name as the top-level key, with `apiKey` and `apiSecret`).
+End-to-end runs require Cloudinary credentials in `process.env`. The `onPrepare` hook in `wdio.conf.ts` reads `E2E_CLOUD`, `E2E_API_KEY`, and `E2E_API_SECRET`, then writes a workspace-local `.cloudinary/environments.json` inside a temporary e2e workspace. This keeps test runs from overwriting the user's `~/.cloudinary/environments.json`.
 
 | Variable | Description |
 |----------|-------------|
@@ -21,6 +21,12 @@ End-to-end runs require Cloudinary credentials in `process.env`. The `onPrepare`
 
 **Local:** add a `test/e2e/.env` file (gitignored) such as:
 
+```bash
+E2E_CLOUD=your_cloud_name
+E2E_API_KEY=your_api_key
+E2E_API_SECRET=your_api_secret
+```
+
 ## Running Tests
 
 ```bash
diff --git a/test/e2e/assets/sample_raw.txt b/test/e2e/assets/sample_raw.txt
new file mode 100644
index 0000000..b1a3da3
--- /dev/null
+++ b/test/e2e/assets/sample_raw.txt
@@ -0,0 +1 @@
+Cloudinary VS Code e2e raw asset fixture.
diff --git a/test/e2e/patches/wdio-vscode-service@6.1.4.patch b/test/e2e/patches/wdio-vscode-service@6.1.4.patch
new file mode 100644
index 0000000..4d31bf1
--- /dev/null
+++ b/test/e2e/patches/wdio-vscode-service@6.1.4.patch
@@ -0,0 +1,21 @@
+diff --git a/dist/service.js b/dist/service.js
+index 221673f49ba513910b707dcc4993f313811e705e..5e83d247eae041ef4eefabdccce66b184b386293 100644
+--- a/dist/service.js
++++ b/dist/service.js
+@@ -115,7 +115,15 @@ export default class VSCodeWorkerService {
+             customArgs.verbose = true;
+             customArgs.logExtensionHostCommunication = true;
+         }
+-        const binary = path.join(__dirname, 'chromium', `index.${process.platform === 'win32' ? 'exe' : 'js'}`);
++        const wrapperBinary = path.join(__dirname, 'chromium', `index.${process.platform === 'win32' ? 'exe' : 'js'}`);
++        let binary = wrapperBinary;
++        if (process.platform !== 'win32') {
++            binary = path.join(storagePath, 'wdio-vscode-chromium-shim.sh');
++            const escapeShellArg = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
++            const shim = `#!/bin/sh\nexec ${escapeShellArg(process.execPath)} ${escapeShellArg(wrapperBinary)} "$@"\n`;
++            await fs.writeFile(binary, shim, 'utf-8');
++            await fs.chmod(binary, 0o755);
++        }
+         const args = Object.entries({ ...customArgs, ...this._vscodeOptions.vscodeArgs }).reduce((prev, [key, value]) => {
+             const decamelizedKey = decamelize(key, { separator: '-' });
+             if (Array.isArray(value)) {
diff --git a/test/e2e/pnpm-lock.yaml b/test/e2e/pnpm-lock.yaml
index e8f9f44..76e288d 100644
--- a/test/e2e/pnpm-lock.yaml
+++ b/test/e2e/pnpm-lock.yaml
@@ -4,6 +4,11 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+patchedDependencies:
+  wdio-vscode-service@6.1.4:
+    hash: 5f09392689eab93e7e286de3e82ca5d26ad35c8856421f3a3a82c39f85a6350a
+    path: patches/wdio-vscode-service@6.1.4.patch
+
 importers:
 
   .:
@@ -43,7 +48,7 @@ importers:
         version: 6.2.0(expect-webdriverio@5.6.5)(webdriverio@9.27.0)
       wdio-vscode-service:
         specifier: ^6.1.4
-        version: 6.1.4(webdriverio@9.27.0)
+        version: 6.1.4(patch_hash=5f09392689eab93e7e286de3e82ca5d26ad35c8856421f3a3a82c39f85a6350a)(webdriverio@9.27.0)
       webdriverio:
         specifier: ^9.27.0
         version: 9.27.0
@@ -5146,7 +5151,7 @@ snapshots:
       - expect-webdriverio
       - webdriverio
 
-  wdio-vscode-service@6.1.4(webdriverio@9.27.0):
+  wdio-vscode-service@6.1.4(patch_hash=5f09392689eab93e7e286de3e82ca5d26ad35c8856421f3a3a82c39f85a6350a)(webdriverio@9.27.0):
     dependencies:
       '@fastify/cors': 9.0.1
       '@fastify/static': 7.0.4
diff --git a/test/e2e/pnpm-workspace.yaml b/test/e2e/pnpm-workspace.yaml
new file mode 100644
index 0000000..701c78d
--- /dev/null
+++ b/test/e2e/pnpm-workspace.yaml
@@ -0,0 +1,2 @@
+patchedDependencies:
+  wdio-vscode-service@6.1.4: patches/wdio-vscode-service@6.1.4.patch
diff --git a/test/e2e/specs/homescreenInteractions.spec.ts b/test/e2e/specs/homescreenInteractions.spec.ts
new file mode 100644
index 0000000..963ebc9
--- /dev/null
+++ b/test/e2e/specs/homescreenInteractions.spec.ts
@@ -0,0 +1,47 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { CloudinarySDK } from '../src/sdks/cloudinarySDK.js';
+import { activityBarUtils } from '../src/vscodeComponentsUtils/ActivityBarUtils.js';
+import { sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js';
+import { pathUtils } from '../src/utils/pathUtils.js';
+import { createHookError } from '../src/utils/errorUtils.js';
+import { libraryViewPage } from '../src/webViewTabs/LibraryViewPage.js';
+
+describe('Homescreen interactions', () => {
+    const cloudinarySDK = new CloudinarySDK();
+    const assetPublicID = `e2e-home-${crypto.randomUUID().substring(0, 8)}`;
+
+    beforeEach(async () => {
+        try {
+            await cloudinarySDK.V2.uploader.upload(
+                path.join(pathUtils.getTestAssetsPath(), 'sample_png.png'),
+                { public_id: assetPublicID }
+            );
+        } catch (error) {
+            throw createHookError('Error uploading homescreen search asset', error);
+        }
+    });
+
+    afterEach(async () => {
+        try {
+            await cloudinarySDK.V2.api.delete_resources([assetPublicID]);
+        } catch (error) {
+            throw createHookError('Error deleting homescreen search asset', error);
+        }
+    });
+
+    it('should show connected controls and search the library from the homescreen', async () => {
+        await activityBarUtils.openView('Cloudinary');
+
+        await sideBarViewUtils.homeScreenViewPage.waitForConnected();
+        await sideBarViewUtils.homeScreenViewPage.validateDocsAiLauncherReady();
+        await sideBarViewUtils.homeScreenViewPage.validateDocsAiPromptEnablesSubmit('How do I upload images?');
+        await sideBarViewUtils.homeScreenViewPage.validateAiToolsPanelReadyAndSelectionEnablesApply();
+        await sideBarViewUtils.homeScreenViewPage.fillSearchInput(assetPublicID);
+
+        await libraryViewPage.waitForLoaded();
+        await libraryViewPage.validateSearchInputValue(assetPublicID);
+        await libraryViewPage.validateAssetsExist([assetPublicID]);
+        await libraryViewPage.validateVisibleAssetCount(1);
+    });
+});
diff --git a/test/e2e/specs/libraryFiltersAndPreview.spec.ts b/test/e2e/specs/libraryFiltersAndPreview.spec.ts
new file mode 100644
index 0000000..ec44b1d
--- /dev/null
+++ b/test/e2e/specs/libraryFiltersAndPreview.spec.ts
@@ -0,0 +1,70 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { CloudinarySDK } from '../src/sdks/cloudinarySDK.js';
+import { activityBarUtils } from '../src/vscodeComponentsUtils/ActivityBarUtils.js';
+import { sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js';
+import { pathUtils } from '../src/utils/pathUtils.js';
+import { createHookError } from '../src/utils/errorUtils.js';
+import { libraryViewPage } from '../src/webViewTabs/LibraryViewPage.js';
+import { assetPreviewTab } from '../src/webViewTabs/AssetPreviewTab.js';
+
+describe('Library filters and preview', () => {
+    const cloudinarySDK = new CloudinarySDK();
+    const assetPrefix = `e2e-lib-${crypto.randomUUID().substring(0, 8)}`;
+    const imagePublicID = `${assetPrefix}-image`;
+    const rawPublicID = `${assetPrefix}-raw.txt`;
+
+    beforeEach(async () => {
+        try {
+            await cloudinarySDK.V2.uploader.upload(
+                path.join(pathUtils.getTestAssetsPath(), 'sample_png.png'),
+                { public_id: imagePublicID }
+            );
+            await cloudinarySDK.V2.uploader.upload(
+                path.join(pathUtils.getTestAssetsPath(), 'sample_raw.txt'),
+                { public_id: rawPublicID, resource_type: 'raw' }
+            );
+        } catch (error) {
+            throw createHookError('Error uploading library filter assets', error);
+        }
+    });
+
+    afterEach(async () => {
+        try {
+            await cloudinarySDK.V2.api.delete_resources([imagePublicID], { resource_type: 'image' });
+            await cloudinarySDK.V2.api.delete_resources([rawPublicID], { resource_type: 'raw' });
+        } catch (error) {
+            throw createHookError('Error deleting library filter assets', error);
+        }
+    });
+
+    it('should filter searched assets by type and open an asset preview', async () => {
+        await activityBarUtils.openView('Cloudinary');
+        await sideBarViewUtils.homeScreenViewPage.clickBrowseLibraryButton();
+
+        await libraryViewPage.waitForLoaded();
+        await libraryViewPage.fillSearchInput(assetPrefix);
+        await libraryViewPage.validateAssetsExist([imagePublicID, rawPublicID]);
+        await libraryViewPage.validateVisibleAssetCount(2);
+
+        await libraryViewPage.setSortDirection('asc');
+        await libraryViewPage.validateFilterState('all', 'asc');
+
+        await libraryViewPage.setResourceTypeFilter('raw');
+        await libraryViewPage.validateFilterState('raw', 'asc');
+        await libraryViewPage.validateAssetHasResourceType(rawPublicID, 'raw');
+        await libraryViewPage.validateVisibleAssetCount(1);
+        await libraryViewPage.validateAssetsNotVisible([imagePublicID]);
+
+        await libraryViewPage.setResourceTypeFilter('image');
+        await libraryViewPage.validateFilterState('image', 'asc');
+        await libraryViewPage.validateAssetHasResourceType(imagePublicID, 'image');
+        await libraryViewPage.validateVisibleAssetCount(1);
+        await libraryViewPage.validateAssetsNotVisible([rawPublicID]);
+
+        await libraryViewPage.clickAsset(imagePublicID);
+        await assetPreviewTab.switchToAsset(imagePublicID);
+        await assetPreviewTab.validateAssetDetails(imagePublicID);
+        await assetPreviewTab.switchBack();
+    });
+});
diff --git a/test/e2e/specs/loadMlAssets.spec.ts b/test/e2e/specs/loadMlAssets.spec.ts
index ec68940..109c5a0 100644
--- a/test/e2e/specs/loadMlAssets.spec.ts
+++ b/test/e2e/specs/loadMlAssets.spec.ts
@@ -4,6 +4,8 @@ import { activityBarUtils } from '../src/vscodeComponentsUtils/ActivityBarUtils.
 import { sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js'
 import crypto from 'node:crypto';
 import { pathUtils } from '../src/utils/pathUtils.js';
+import { createHookError } from '../src/utils/errorUtils.js';
+import { libraryViewPage } from '../src/webViewTabs/LibraryViewPage.js';
 
 /**
  * Asset Explorer Tests: 
@@ -19,7 +21,7 @@ describe('Asset Explorer Tetsts', () => {
             await cloudinarySDK.V2.uploader.upload(path.join(pathUtils.getTestAssetsPath(), 'sample_png.png'), { public_id: firstAssetPublicID });
             await cloudinarySDK.V2.uploader.upload(path.join(pathUtils.getTestAssetsPath(), 'sample_png.png'), { public_id: secondAssetPublicID });
         } catch (error) {
-            throw new Error('Error uploading assets:', error);
+            throw createHookError('Error uploading assets', error);
         }
     });
 
@@ -27,7 +29,7 @@ describe('Asset Explorer Tetsts', () => {
         try {
             await cloudinarySDK.V2.api.delete_resources([firstAssetPublicID, secondAssetPublicID]);
         } catch (error) {
-            throw new Error('Error deleting assets:', error);
+            throw createHookError('Error deleting assets', error);
         }
     });
 
@@ -35,15 +37,12 @@ describe('Asset Explorer Tetsts', () => {
      * Validates that the title and content of the Cloudinary media library are loaded correctly.
      */
     it('should load cloudinary media library', async () => {
-        const expectedTitle = 'CLOUDINARY';
         const expectedItems = [firstAssetPublicID, secondAssetPublicID];
         
         await activityBarUtils.openView('Cloudinary');
         await sideBarViewUtils.homeScreenViewPage.clickBrowseLibraryButton();
 
-        await sideBarViewUtils.validateSideBarViewTitle(expectedTitle);
-
-        await sideBarViewUtils.validateContentItemsExist(expectedItems);
+        await libraryViewPage.waitForLoaded();
+        await libraryViewPage.validateAssetsExist(expectedItems);
     });
 });
-
diff --git a/test/e2e/specs/searchAssetFromSideBar.spec.ts b/test/e2e/specs/searchAssetFromSideBar.spec.ts
index 28c3eca..5dfe8bf 100644
--- a/test/e2e/specs/searchAssetFromSideBar.spec.ts
+++ b/test/e2e/specs/searchAssetFromSideBar.spec.ts
@@ -2,8 +2,10 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { CloudinarySDK } from '../src/sdks/cloudinarySDK.js';
 import { activityBarUtils } from '../src/vscodeComponentsUtils/ActivityBarUtils.js';
-import { SideBarViewActions, sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js';
+import { sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js';
 import { pathUtils } from '../src/utils/pathUtils.js';
+import { createHookError } from '../src/utils/errorUtils.js';
+import { libraryViewPage } from '../src/webViewTabs/LibraryViewPage.js';
 
 describe('Search asset from side bar', () => {
 
@@ -17,7 +19,7 @@ describe('Search asset from side bar', () => {
                 { public_id: assetPublicID }
             );
         } catch (error) {
-            throw new Error('Error uploading asset:', error);
+            throw createHookError('Error uploading asset', error);
         }
     });
 
@@ -25,20 +27,18 @@ describe('Search asset from side bar', () => {
         try {
             await cloudinarySDK.V2.api.delete_resources([assetPublicID]);
         } catch (error) {
-            throw new Error('Error deleting asset:', error);
+            throw createHookError('Error deleting asset', error);
         }
     });
 
     it('should find the uploaded asset via sidebar search', async () => {
         await activityBarUtils.openView('Cloudinary');
         await sideBarViewUtils.homeScreenViewPage.clickBrowseLibraryButton();
-        await sideBarViewUtils.waitContentToLoad();
 
-        await sideBarViewUtils.clickAction(SideBarViewActions.SEARCH);
+        await libraryViewPage.waitForLoaded();
+        await libraryViewPage.fillSearchInput(assetPublicID);
 
-        await sideBarViewUtils.homeScreenViewPage.fillSearchInput(assetPublicID);
-
-        await sideBarViewUtils.validateContentItemsExist(['Clear Search', assetPublicID]);
-        await sideBarViewUtils.validateContentItemsNumber(2);
+        await libraryViewPage.validateAssetsExist([assetPublicID]);
+        await libraryViewPage.validateVisibleAssetCount(1);
     });
 });
diff --git a/test/e2e/specs/uploadFromSideBarView.spec.ts b/test/e2e/specs/uploadFromSideBarView.spec.ts
index e520879..ad7da48 100644
--- a/test/e2e/specs/uploadFromSideBarView.spec.ts
+++ b/test/e2e/specs/uploadFromSideBarView.spec.ts
@@ -1,19 +1,21 @@
 import path from "path";
 import { CloudinarySDK } from "../src/sdks/cloudinarySDK.js";
 import { pathUtils } from "../src/utils/pathUtils.js";
-import { SideBarViewActions, sideBarViewUtils } from "../src/vscodeComponentsUtils/SideBarViewUtils.js";
+import { sideBarViewUtils } from "../src/vscodeComponentsUtils/SideBarViewUtils.js";
 import { activityBarUtils } from "../src/vscodeComponentsUtils/ActivityBarUtils.js";
 import { uploadToCloudinaryTab } from "../src/webViewTabs/UploadToCloudinaryTab.js";
 import * as fs from 'node:fs';
 import { expect } from "@wdio/globals";
 import allureReporter from '@wdio/allure-reporter'
+import { createHookError } from "../src/utils/errorUtils.js";
+import { libraryViewPage } from "../src/webViewTabs/LibraryViewPage.js";
 
 describe('Upload asset from side bar Upload button', () => {
 
     const cloudinarySDK = new CloudinarySDK();
     const assetPath = path.join(pathUtils.getTestAssetsPath(), 'sample_png.png');
 
-    const newFileName = `${crypto.randomUUID().substring(0, 8)}.png`;    
+    const newFileName = `${crypto.randomUUID().substring(0, 8)}.png`;
     const newFilePath = path.join(pathUtils.getTempFolderPath(), newFileName);
 
     const firstAssetPublicID = `e2e-test-ae-${crypto.randomUUID().substring(0, 8)}`;
@@ -23,7 +25,7 @@ describe('Upload asset from side bar Upload button', () => {
             // Copy with a unique name so the sidebar shows the display name (not the public ID) in dynamic folder environments
             fs.copyFileSync(assetPath, newFilePath);
         } catch (error) {
-            throw new Error('Error copying asset:', error);
+            throw createHookError('Error copying asset', error);
         }
     });
 
@@ -31,20 +33,21 @@ describe('Upload asset from side bar Upload button', () => {
         try {
             await cloudinarySDK.V2.api.delete_resources([firstAssetPublicID]);
         } catch (error) {
-            throw new Error('Error deleting assets:', error);
+            throw createHookError('Error deleting assets', error);
         }
     });
 
     it('should upload an asset using the side bar Upload button with custom public ID', async () => {
         await activityBarUtils.openView('Cloudinary');
         await sideBarViewUtils.homeScreenViewPage.clickBrowseLibraryButton();
-        
-        await sideBarViewUtils.clickAction(SideBarViewActions.UPLOAD);
+
+        await libraryViewPage.waitForLoaded();
+        await libraryViewPage.clickToolbarAction('openUploadWidget');
 
         await uploadToCloudinaryTab.switchTo();
         await uploadToCloudinaryTab.openAdvancedOptions();
         await uploadToCloudinaryTab.fillCustomPublicId(firstAssetPublicID);
-        
+
         await uploadToCloudinaryTab.uploadLocalFile(newFilePath);
 
         await uploadToCloudinaryTab.switchBack();
@@ -53,13 +56,12 @@ describe('Upload asset from side bar Upload button', () => {
 
         await cloudinarySDK.waitUntilAssetIsUploaded(firstAssetPublicID);
 
-        await sideBarViewUtils.clickAction(SideBarViewActions.REFRESH);
+        await libraryViewPage.clickToolbarAction('refresh');
 
-        await sideBarViewUtils.validateContentItemsExist([newFileName.replace('.png', '')]);
+        await libraryViewPage.validateAssetsExist([firstAssetPublicID]);
 
         await allureReporter.addStep('Validate that the asset was uploaded with the correct display name');
         const byPublicId = await cloudinarySDK.V2.api.resource(firstAssetPublicID);
         expect(byPublicId.display_name).toBe(newFileName.replace('.png', ''));
     });
 });
-
diff --git a/test/e2e/specs/uploadWidgetControls.spec.ts b/test/e2e/specs/uploadWidgetControls.spec.ts
new file mode 100644
index 0000000..919854e
--- /dev/null
+++ b/test/e2e/specs/uploadWidgetControls.spec.ts
@@ -0,0 +1,18 @@
+import { activityBarUtils } from '../src/vscodeComponentsUtils/ActivityBarUtils.js';
+import { sideBarViewUtils } from '../src/vscodeComponentsUtils/SideBarViewUtils.js';
+import { uploadToCloudinaryTab } from '../src/webViewTabs/UploadToCloudinaryTab.js';
+
+describe('Upload widget controls', () => {
+    it('should open from the homescreen with folder and preset controls ready', async () => {
+        await activityBarUtils.openView('Cloudinary');
+
+        await sideBarViewUtils.homeScreenViewPage.waitForConnected();
+        await sideBarViewUtils.homeScreenViewPage.clickUploadButton();
+
+        await uploadToCloudinaryTab.switchTo();
+        await uploadToCloudinaryTab.validateUploadControlsReady();
+        await uploadToCloudinaryTab.waitForFolderOptionsLoaded();
+        await uploadToCloudinaryTab.validateRootFolderOption();
+        await uploadToCloudinaryTab.switchBack();
+    });
+});
diff --git a/test/e2e/src/utils/errorUtils.ts b/test/e2e/src/utils/errorUtils.ts
new file mode 100644
index 0000000..af61d6b
--- /dev/null
+++ b/test/e2e/src/utils/errorUtils.ts
@@ -0,0 +1,35 @@
+function getRecordValue(record: Record<string, unknown>, key: string): string | undefined {
+    const value = record[key];
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
+}
+
+export function formatError(error: unknown): string {
+    if (error && typeof error === 'object') {
+        const record = error as Record<string, unknown>;
+        const message = [
+            getRecordValue(record, 'name'),
+            getRecordValue(record, 'message'),
+        ].filter(Boolean).join(': ');
+        const httpCode = getRecordValue(record, 'http_code');
+        if (message) {
+            return httpCode ? `${message} (http_code=${httpCode})` : message;
+        }
+    }
+
+    if (error instanceof Error) {
+        const details = [error.name, error.message].filter(Boolean).join(': ');
+        const record = error as Error & Record<string, unknown>;
+        const httpCode = getRecordValue(record, 'http_code');
+        return httpCode ? `${details} (http_code=${httpCode})` : details;
+    }
+
+    return String(error);
+}
+
+export function createHookError(message: string, error: unknown): Error {
+    const wrappedError = new Error(`${message}: ${formatError(error)}`);
+    if (error instanceof Error && error.stack) {
+        wrappedError.stack = `${wrappedError.stack}\nCaused by: ${error.stack}`;
+    }
+    return wrappedError;
+}
diff --git a/test/e2e/src/utils/wdioUtils.ts b/test/e2e/src/utils/wdioUtils.ts
index 5bd2d5b..ef22904 100644
--- a/test/e2e/src/utils/wdioUtils.ts
+++ b/test/e2e/src/utils/wdioUtils.ts
@@ -30,4 +30,4 @@ class WdioUtils {
     }
 }
 
-export default new WdioUtils();
\ No newline at end of file
+export default new WdioUtils();
diff --git a/test/e2e/src/vscodeComponentsUtils/SideBarViewUtils.ts b/test/e2e/src/vscodeComponentsUtils/SideBarViewUtils.ts
index 0b01c5d..9c3c7cb 100644
--- a/test/e2e/src/vscodeComponentsUtils/SideBarViewUtils.ts
+++ b/test/e2e/src/vscodeComponentsUtils/SideBarViewUtils.ts
@@ -17,7 +17,7 @@ export enum SideBarViewActions {
  */
 class SideBarViewUtils {
     public readonly homeScreenViewPage = new HomeScreenViewPage();
-    
+
     /**
      * Gets the Side Bar View instance.
      */
@@ -133,4 +133,4 @@ class SideBarViewUtils {
         
 }
 
-export const sideBarViewUtils = new SideBarViewUtils()
\ No newline at end of file
+export const sideBarViewUtils = new SideBarViewUtils()
diff --git a/test/e2e/src/vscodeComponentsUtils/WebViewUtils.ts b/test/e2e/src/vscodeComponentsUtils/WebViewUtils.ts
index 00c39f5..1d93fd6 100644
--- a/test/e2e/src/vscodeComponentsUtils/WebViewUtils.ts
+++ b/test/e2e/src/vscodeComponentsUtils/WebViewUtils.ts
@@ -1,4 +1,5 @@
 import { browser } from "@wdio/globals"
+import allureReporter from '@wdio/allure-reporter'
 
 
 class WebViewUtils {
@@ -6,6 +7,7 @@ class WebViewUtils {
      * Gets the WebView instance by exact title match.
      */
     public async getWebView(title: string) {
+        await allureReporter.addStep(`Get WebView with title "${title}"`);
         const workbench = await browser.getWorkbench()
         const exactMatch = new RegExp(`^${title}$`);
         return browser.waitUntil(() => workbench.getWebviewByTitle(exactMatch), {
@@ -14,4 +16,4 @@ class WebViewUtils {
     }
 }
 
-export const webViewUtils = new WebViewUtils()
\ No newline at end of file
+export const webViewUtils = new WebViewUtils()
diff --git a/test/e2e/src/webViewTabs/AssetPreviewTab.ts b/test/e2e/src/webViewTabs/AssetPreviewTab.ts
new file mode 100644
index 0000000..42b92fe
--- /dev/null
+++ b/test/e2e/src/webViewTabs/AssetPreviewTab.ts
@@ -0,0 +1,40 @@
+import { browser, expect } from "@wdio/globals";
+import allureReporter from '@wdio/allure-reporter';
+import { WebViewTabBase } from "./WebViewTabBase.js";
+
+function getPreviewTitle(publicId: string): string {
+    return publicId.includes('/')
+        ? publicId.split('/').pop() || publicId
+        : publicId;
+}
+
+class AssetPreviewTab extends WebViewTabBase {
+    constructor() {
+        super('');
+    }
+
+    public async switchToAsset(publicId: string) {
+        await allureReporter.addStep(`Switch to asset preview for "${publicId}"`);
+        this.title = getPreviewTitle(publicId);
+        await this.switchTo();
+    }
+
+    public async validateAssetDetails(publicId: string) {
+        await allureReporter.addStep(`Validate asset preview details for "${publicId}"`);
+        const title = await browser.$('.asset-header__title');
+        await title.waitForDisplayed();
+        expect(await title.getText()).toBe(getPreviewTitle(publicId));
+
+        const previewCard = await browser.$('.card--elevated');
+        await previewCard.waitForDisplayed();
+        expect(await previewCard.getText()).toContain(publicId);
+
+        const infoTab = await browser.$('[data-tab="info"]');
+        await infoTab.waitForDisplayed();
+
+        const urlsTab = await browser.$('[data-tab="urls"]');
+        await urlsTab.waitForDisplayed();
+    }
+}
+
+export const assetPreviewTab = new AssetPreviewTab();
diff --git a/test/e2e/src/webViewTabs/HomeScreenViewPage.ts b/test/e2e/src/webViewTabs/HomeScreenViewPage.ts
index ee11c2c..748191c 100644
--- a/test/e2e/src/webViewTabs/HomeScreenViewPage.ts
+++ b/test/e2e/src/webViewTabs/HomeScreenViewPage.ts
@@ -1,4 +1,4 @@
-import { $, browser } from '@wdio/globals';
+import { browser, expect } from '@wdio/globals';
 import wdioUtils from '../utils/wdioUtils.js';
 import { WebViewTabBase } from './WebViewTabBase.js';
 import allureReporter from '@wdio/allure-reporter';
@@ -6,6 +6,25 @@ import { Key } from 'webdriverio'
 
 const HOME_SCREEN_BROWSE_LIBRARY_BUTTON_SELECTOR = '//*[@data-testid="hs-browse-library-button"]';
 const SEARCH_INPUT_SELECTOR = '//*[@data-testid="hs-search-input-selector"]';
+const STATUS_TEXT_SELECTOR = '#hs-status-text';
+const CLOUD_NAME_SELECTOR = '#hs-cloud-name';
+const FOLDER_MODE_SELECTOR = '#hs-folder-mode';
+const SEARCH_CONTAINER_SELECTOR = '#hs-search';
+const UPLOAD_BUTTON_SELECTOR = '#hs-btn-upload';
+const DOCS_AI_HEADING_SELECTOR = '#hs-docs-ai-heading';
+const DOCS_AI_INPUT_SELECTOR = '#hs-docs-ai-input';
+const DOCS_AI_SUBMIT_SELECTOR = '#hs-docs-ai-submit';
+const DOCS_AI_CHIP_SELECTOR = '.hs-docs-ai-chip';
+const AI_TOOLS_BUTTON_SELECTOR = '#hs-btn-ai-tools';
+const AI_TOOLS_PANEL_SELECTOR = '#hs-ai-panel';
+const AI_TOOLS_READY_STATE_SELECTOR = '#hs-ai-state-ready';
+const AI_TOOLS_ERROR_STATE_SELECTOR = '#hs-ai-state-error';
+const AI_TOOLS_PLATFORM_SELECT_SELECTOR = '#hs-ai-platform-select';
+const AI_TOOLS_SCOPE_BUTTON_SELECTOR = '.hs-ai-scope-btn';
+const AI_TOOLS_SKILL_CHECKBOX_SELECTOR = '.hs-ai-cb[data-skill]';
+const AI_TOOLS_MCP_CHECKBOX_SELECTOR = '.hs-ai-cb[data-mcp]';
+const AI_TOOLS_AVAILABLE_CHECKBOX_SELECTOR = '.hs-ai-cb:not(:disabled)';
+const AI_TOOLS_APPLY_BUTTON_SELECTOR = '#hs-ai-apply';
 
 /**
  * Page object for the Home Screen View.
@@ -18,6 +37,44 @@ export class HomeScreenViewPage extends WebViewTabBase {
     super('Cloudinary');
   }
 
+  /**
+   * Waits for the homescreen to show a connected Cloudinary account.
+   */
+  public async waitForConnected() {
+    await allureReporter.addStep('Wait for connected homescreen state');
+    await this.switchTo();
+    try {
+      let latestStatus = '';
+      let latestCloudName = '';
+      await browser.waitUntil(async () => {
+        const status = await browser.$(STATUS_TEXT_SELECTOR);
+        const cloudName = await browser.$(CLOUD_NAME_SELECTOR);
+        const folderMode = await browser.$(FOLDER_MODE_SELECTOR);
+        const search = await browser.$(SEARCH_CONTAINER_SELECTOR);
+
+        if (!(await status.isExisting()) || !(await cloudName.isExisting())) {
+          return false;
+        }
+
+        latestStatus = (await status.getText()).trim();
+        latestCloudName = (await cloudName.getText()).trim();
+        return latestStatus === 'Connected'
+          && latestCloudName.length > 0
+          && latestCloudName !== 'Not configured'
+          && await folderMode.isDisplayed()
+          && await search.isDisplayed();
+      }, {
+        timeout: 20000,
+        timeoutMsg: `Timed out waiting for connected homescreen state. Latest status: "${latestStatus}", cloud: "${latestCloudName}"`,
+      });
+
+      expect(latestStatus).toBe('Connected');
+      expect(latestCloudName).not.toBe('Not configured');
+    } finally {
+      await this.switchBack();
+    }
+  }
+
   /**
    * Clicks the Browse Library button.
    */
@@ -46,4 +103,131 @@ export class HomeScreenViewPage extends WebViewTabBase {
       await this.switchBack();
     }
   }
+
+  /**
+   * Clicks the Upload button.
+   */
+  public async clickUploadButton() {
+    await allureReporter.addStep('Click Upload button');
+    await this.switchTo();
+    try {
+      await wdioUtils.click(UPLOAD_BUTTON_SELECTOR);
+    } finally {
+      await this.switchBack();
+    }
+  }
+
+  /**
+   * Validates that the Docs AI launcher UI is ready on the homescreen.
+   */
+  public async validateDocsAiLauncherReady() {
+    await allureReporter.addStep('Validate Docs AI launcher is ready');
+    await this.switchTo();
+    try {
+      const heading = await browser.$(DOCS_AI_HEADING_SELECTOR);
+      await heading.waitForDisplayed();
+      expect(await heading.getText()).toBe('Ask Cloudinary AI');
+
+      const input = await browser.$(DOCS_AI_INPUT_SELECTOR);
+      await input.waitForDisplayed();
+
+      const submit = await browser.$(DOCS_AI_SUBMIT_SELECTOR);
+      await submit.waitForExist();
+      expect(await submit.isEnabled()).toBe(false);
+
+      const chips = await browser.$$(DOCS_AI_CHIP_SELECTOR);
+      expect(chips.length).toBeGreaterThanOrEqual(4);
+    } finally {
+      await this.switchBack();
+    }
+  }
+
+  /**
+   * Validates that entering a Docs AI prompt enables the submit control.
+   */
+  public async validateDocsAiPromptEnablesSubmit(prompt: string) {
+    await allureReporter.addStep(`Validate Docs AI prompt enables submit: '${prompt}'`);
+    await this.switchTo();
+    try {
+      const input = await browser.$(DOCS_AI_INPUT_SELECTOR);
+      await input.waitForDisplayed();
+      await input.setValue(prompt);
+
+      const submit = await browser.$(DOCS_AI_SUBMIT_SELECTOR);
+      await browser.waitUntil(async () => submit.isEnabled(), {
+        timeout: 5000,
+        timeoutMsg: 'Docs AI submit button did not enable after entering a prompt',
+      });
+      expect(await submit.isEnabled()).toBe(true);
+    } finally {
+      await this.switchBack();
+    }
+  }
+
+  /**
+   * Validates that the AI tools accordion can hydrate host data and selection state.
+   */
+  public async validateAiToolsPanelReadyAndSelectionEnablesApply() {
+    await allureReporter.addStep('Validate AI tools panel loads and selection enables Apply');
+    await this.switchTo();
+    try {
+      const button = await browser.$(AI_TOOLS_BUTTON_SELECTOR);
+      await button.waitForClickable();
+      await button.click();
+
+      const panel = await browser.$(AI_TOOLS_PANEL_SELECTOR);
+      await panel.waitForDisplayed();
+      await browser.waitUntil(async () => {
+        const errorState = await browser.$(AI_TOOLS_ERROR_STATE_SELECTOR);
+        if (await errorState.isExisting()) {
+          const errorClass = await errorState.getAttribute('class');
+          if (!errorClass.includes('hidden')) {
+            throw new Error(`AI tools panel failed to load: ${(await errorState.getText()).trim()}`);
+          }
+        }
+
+        const readyState = await browser.$(AI_TOOLS_READY_STATE_SELECTOR);
+        if (!(await readyState.isExisting())) {
+          return false;
+        }
+        const readyClass = await readyState.getAttribute('class');
+        return !readyClass.includes('hidden');
+      }, {
+        timeout: 30000,
+        timeoutMsg: 'Timed out waiting for AI tools panel data',
+      });
+
+      expect(await button.getAttribute('aria-expanded')).toBe('true');
+
+      const platformSelect = await browser.$(AI_TOOLS_PLATFORM_SELECT_SELECTOR);
+      await platformSelect.waitForDisplayed();
+      const platformOptions = await browser.$$(`${AI_TOOLS_PLATFORM_SELECT_SELECTOR} option`);
+      expect(platformOptions.length).toBeGreaterThan(1);
+
+      const scopeButtons = await browser.$$(AI_TOOLS_SCOPE_BUTTON_SELECTOR);
+      expect(scopeButtons.length).toBe(2);
+
+      const skillRows = await browser.$$(AI_TOOLS_SKILL_CHECKBOX_SELECTOR);
+      expect(skillRows.length).toBeGreaterThan(0);
+      const mcpRows = await browser.$$(AI_TOOLS_MCP_CHECKBOX_SELECTOR);
+      expect(mcpRows.length).toBeGreaterThan(0);
+
+      const applyButton = await browser.$(AI_TOOLS_APPLY_BUTTON_SELECTOR);
+      await applyButton.waitForDisplayed();
+      expect(await applyButton.isEnabled()).toBe(false);
+
+      const availableCheckbox = await browser.$(AI_TOOLS_AVAILABLE_CHECKBOX_SELECTOR);
+      await availableCheckbox.waitForExist();
+      await availableCheckbox.scrollIntoView();
+      await availableCheckbox.click();
+
+      await browser.waitUntil(async () => applyButton.isEnabled(), {
+        timeout: 5000,
+        timeoutMsg: 'AI tools Apply button did not enable after selecting an available item',
+      });
+      expect(await applyButton.isEnabled()).toBe(true);
+    } finally {
+      await this.switchBack();
+    }
+  }
 }
diff --git a/test/e2e/src/webViewTabs/LibraryViewPage.ts b/test/e2e/src/webViewTabs/LibraryViewPage.ts
new file mode 100644
index 0000000..e9a7c2f
--- /dev/null
+++ b/test/e2e/src/webViewTabs/LibraryViewPage.ts
@@ -0,0 +1,263 @@
+import { browser, expect } from "@wdio/globals";
+import allureReporter from '@wdio/allure-reporter';
+import { Key } from 'webdriverio';
+import { WebViewTabBase } from "./WebViewTabBase.js";
+
+type ResourceTypeFilter = 'all' | 'image' | 'video' | 'raw';
+type SortDirection = 'desc' | 'asc';
+
+function cssAttributeValue(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+class LibraryViewPage extends WebViewTabBase {
+    constructor() {
+        super('Cloudinary Media Library');
+    }
+
+    public async waitForLoaded() {
+        await allureReporter.addStep('Wait for library webview to load');
+        await this.switchTo();
+        try {
+            const root = await browser.$('#lib-root');
+            await root.waitForExist();
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async clickToolbarAction(action: 'openUploadWidget' | 'refresh') {
+        await allureReporter.addStep(`Click library toolbar action: ${action}`);
+        await this.switchTo();
+        try {
+            const button = await browser.$(`[data-cld-action-toolbar] [data-action="${action}"]`);
+            await button.waitForClickable();
+            await button.click();
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async setResourceTypeFilter(filter: ResourceTypeFilter) {
+        await allureReporter.addStep(`Set library resource type filter to "${filter}"`);
+        await this.switchTo();
+        try {
+            const select = await browser.$('#lib-filter-type');
+            await select.waitForDisplayed();
+            await select.selectByAttribute('value', filter);
+            await browser.execute((element: HTMLSelectElement) => {
+                element.dispatchEvent(new Event('change', { bubbles: true }));
+            }, select);
+            await this.waitForFilterValue('#lib-filter-type', filter);
+            await this.waitForRowsToSettle();
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async setSortDirection(sortDirection: SortDirection) {
+        await allureReporter.addStep(`Set library sort direction to "${sortDirection}"`);
+        await this.switchTo();
+        try {
+            const select = await browser.$('#lib-filter-sort');
+            await select.waitForDisplayed();
+            await select.selectByAttribute('value', sortDirection);
+            await browser.execute((element: HTMLSelectElement) => {
+                element.dispatchEvent(new Event('change', { bubbles: true }));
+            }, select);
+            await this.waitForFilterValue('#lib-filter-sort', sortDirection);
+            await this.waitForRowsToSettle();
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateFilterState(filter: ResourceTypeFilter, sortDirection: SortDirection) {
+        await allureReporter.addStep(`Validate library filter state: type "${filter}", sort "${sortDirection}"`);
+        await this.switchTo();
+        try {
+            const typeSelect = await browser.$('#lib-filter-type');
+            const sortSelect = await browser.$('#lib-filter-sort');
+            await typeSelect.waitForDisplayed();
+            await sortSelect.waitForDisplayed();
+            expect(await typeSelect.getValue()).toBe(filter);
+            expect(await sortSelect.getValue()).toBe(sortDirection);
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async fillSearchInput(query: string) {
+        await allureReporter.addStep(`Fill library search input with value '${query}'`);
+        await this.switchTo();
+        try {
+            const input = await browser.$('#lib-search-input');
+            await input.waitForDisplayed();
+            await input.setValue(query);
+            await browser.keys(Key.Enter);
+            await this.waitForSearchResults(query);
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateSearchInputValue(query: string) {
+        await allureReporter.addStep(`Validate library search input value is '${query}'`);
+        await this.switchTo();
+        try {
+            const input = await browser.$('#lib-search-input');
+            await input.waitForDisplayed();
+            expect((await input.getValue()).trim()).toBe(query.trim());
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateAssetsExist(publicIds: string[]) {
+        await allureReporter.addStep(`Validate library assets exist: [${publicIds.join(', ')}]`);
+        await this.switchTo();
+        try {
+            for (const publicId of publicIds) {
+                const selector = `.lib-row--asset[data-public-id="${cssAttributeValue(publicId)}"]`;
+                await browser.waitUntil(async () => {
+                    const asset = await browser.$(selector);
+                    return asset.isExisting();
+                }, {
+                    timeout: 15000,
+                    timeoutMsg: `Timed out waiting for asset "${publicId}" to appear in the library`,
+                });
+            }
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateAssetsNotVisible(publicIds: string[]) {
+        await allureReporter.addStep(`Validate library assets are not visible: [${publicIds.join(', ')}]`);
+        await this.switchTo();
+        try {
+            for (const publicId of publicIds) {
+                const selector = `.lib-row--asset[data-public-id="${cssAttributeValue(publicId)}"]`;
+                await browser.waitUntil(async () => {
+                    const asset = await browser.$(selector);
+                    return !(await asset.isExisting()) || !(await asset.isDisplayed());
+                }, {
+                    timeout: 15000,
+                    timeoutMsg: `Timed out waiting for asset "${publicId}" to be hidden from the library`,
+                });
+            }
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateAssetHasResourceType(publicId: string, resourceType: Exclude<ResourceTypeFilter, 'all'>) {
+        await allureReporter.addStep(`Validate asset "${publicId}" has resource type "${resourceType}"`);
+        await this.switchTo();
+        try {
+            const selector = `.lib-row--asset.lib-row--${resourceType}[data-public-id="${cssAttributeValue(publicId)}"]`;
+            await browser.waitUntil(async () => {
+                const asset = await browser.$(selector);
+                return asset.isExisting();
+            }, {
+                timeout: 15000,
+                timeoutMsg: `Timed out waiting for asset "${publicId}" with resource type "${resourceType}"`,
+            });
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async clickAsset(publicId: string) {
+        await allureReporter.addStep(`Click library asset "${publicId}"`);
+        await this.switchTo();
+        try {
+            const selector = `.lib-row--asset[data-public-id="${cssAttributeValue(publicId)}"]`;
+            const asset = await browser.$(selector);
+            await asset.waitForClickable();
+            await asset.click();
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    public async validateVisibleAssetCount(expectedCount: number) {
+        await allureReporter.addStep(`Validate ${expectedCount} visible asset rows`);
+        await this.switchTo();
+        try {
+            let visibleCount = 0;
+            await browser.waitUntil(async () => {
+                visibleCount = await this.getVisibleAssetRowsCount();
+                return visibleCount === expectedCount;
+            }, {
+                timeout: 15000,
+                timeoutMsg: `Expected ${expectedCount} visible asset rows`,
+            }).catch(() => {
+                throw new Error(`Expected ${expectedCount} visible asset rows, got ${visibleCount}`);
+            });
+            expect(visibleCount).toBe(expectedCount);
+        } finally {
+            await this.switchBack();
+        }
+    }
+
+    private async waitForFilterValue(selector: string, expectedValue: string) {
+        await browser.waitUntil(async () => {
+            const select = await browser.$(selector);
+            return await select.getValue() === expectedValue;
+        }, {
+            timeout: 5000,
+            timeoutMsg: `Expected ${selector} to have value "${expectedValue}"`,
+        });
+    }
+
+    private async waitForRowsToSettle() {
+        await browser.waitUntil(async () => {
+            const loading = await browser.$('#lib-search-loading');
+            const loadingClass = await loading.isExisting()
+                ? await loading.getAttribute('class')
+                : 'hidden';
+            const pendingRows = await browser.$$('.lib-row--search-loading');
+            return loadingClass.includes('hidden') && pendingRows.length === 0;
+        }, {
+            timeout: 15000,
+            timeoutMsg: 'Timed out waiting for library rows to settle',
+        });
+    }
+
+    private async getVisibleAssetRowsCount() {
+        const rows = await browser.$$('.lib-row--asset');
+        let visibleCount = 0;
+        for (const row of rows) {
+            if (await row.isDisplayed()) {
+                visibleCount += 1;
+            }
+        }
+        return visibleCount;
+    }
+
+    private async waitForSearchResults(query: string) {
+        const expectedQuery = query.trim();
+        await browser.waitUntil(async () => {
+            const loading = await browser.$('#lib-search-loading');
+            const loadingClass = await loading.getAttribute('class');
+            const pendingRows = await browser.$$('.lib-row--search-loading');
+            const clearSearchRow = await browser.$('.lib-row--clear');
+            const clearSearchText = await clearSearchRow.isExisting()
+                ? await clearSearchRow.getText()
+                : '';
+            const input = await browser.$('#lib-search-input');
+            const inputValue = await input.getValue();
+
+            return inputValue.trim() === expectedQuery
+                && clearSearchText.includes(expectedQuery)
+                && loadingClass.includes('hidden')
+                && pendingRows.length === 0;
+        }, {
+            timeout: 15000,
+            timeoutMsg: `Timed out waiting for library search results for "${expectedQuery}"`,
+        });
+    }
+}
+
+export const libraryViewPage = new LibraryViewPage();
diff --git a/test/e2e/src/webViewTabs/UploadToCloudinaryTab.ts b/test/e2e/src/webViewTabs/UploadToCloudinaryTab.ts
index 5acd973..078eed5 100644
--- a/test/e2e/src/webViewTabs/UploadToCloudinaryTab.ts
+++ b/test/e2e/src/webViewTabs/UploadToCloudinaryTab.ts
@@ -1,4 +1,4 @@
-import { browser } from "@wdio/globals"
+import { browser, expect } from "@wdio/globals"
 import allureReporter from '@wdio/allure-reporter'
 import { WebViewTabBase } from "./WebViewTabBase.js";
 
@@ -29,10 +29,78 @@ class UploadToCloudinaryTab extends WebViewTabBase {
         await this.waitForAllUploadsToComplete();
     }
 
+    /**
+     * Validates that the upload widget's primary controls rendered.
+     */
+    public async validateUploadControlsReady() {
+        await allureReporter.addStep('Validate upload controls are ready');
+
+        const folderSelect = await browser.$('#folderSelect');
+        await folderSelect.waitForDisplayed();
+
+        const presetSelect = await browser.$('#presetSelect');
+        await presetSelect.waitForDisplayed();
+        expect(await presetSelect.getValue()).toBe('');
+
+        const advancedHeader = await browser.$('#advancedHeader');
+        await advancedHeader.waitForClickable();
+
+        const dropZone = await browser.$('#dropZone');
+        await dropZone.waitForDisplayed();
+        expect(await dropZone.getText()).toContain('Hold Shift, then drag & drop files here');
+
+        const browseButton = await browser.$('#browseBtn');
+        await browseButton.waitForClickable();
+
+        const localTab = await browser.$('[data-tab="local"]');
+        await localTab.waitForDisplayed();
+
+        const urlTab = await browser.$('[data-tab="url"]');
+        await urlTab.waitForDisplayed();
+    }
+
+    /**
+     * Waits until folder options have been hydrated or fallen back to root.
+     */
+    public async waitForFolderOptionsLoaded() {
+        await allureReporter.addStep('Wait for folder options to load');
+
+        await browser.waitUntil(async () => {
+            const loadingHint = await browser.$('#folderLoadingHint');
+            return !(await loadingHint.isExisting());
+        }, {
+            timeout: 15000,
+            timeoutMsg: 'Folder options did not finish loading',
+        });
+    }
+
+    /**
+     * Validates that uploads can still target the root folder.
+     */
+    public async validateRootFolderOption() {
+        await allureReporter.addStep('Validate root folder option exists');
+
+        const folderSelect = await browser.$('#folderSelect');
+        await folderSelect.waitForDisplayed();
+        const options = await browser.execute(() => {
+            return Array.from(document.querySelectorAll<HTMLOptionElement>('#folderSelect option'))
+                .map((option) => ({
+                    label: option.textContent || '',
+                    value: option.value,
+                }));
+        });
+        const labels = options.map((option) => option.label);
+        const values = options.map((option) => option.value);
+        expect(labels).toContain('/ (root)');
+        expect(values).toContain('');
+    }
+
     /**
      * Waits for all uploads to complete.
      */
     public async waitForAllUploadsToComplete() {
+        await allureReporter.addStep('Wait for all uploads to complete');
+        let uploadError: string | undefined;
         await browser.waitUntil(async () => {
             const statuses = await browser.$$('.queue-item__status');
             const count = await statuses.length;
@@ -42,8 +110,16 @@ class UploadToCloudinaryTab extends WebViewTabBase {
 
             const textPromises = await statuses.map(el => el.getText());
             const texts = await Promise.all(textPromises);
+            uploadError = texts.find(text => text !== 'Complete' && !text.endsWith('%') && text !== 'Pending...');
+            if (uploadError) {
+                return true;
+            }
             return texts.every(text => text === 'Complete');
         }, { timeoutMsg: 'Not all uploads completed in time' });
+
+        if (uploadError) {
+            throw new Error(`Upload failed: ${uploadError}`);
+        }
     }
 
     /**
diff --git a/test/e2e/src/webViewTabs/WebViewTabBase.ts b/test/e2e/src/webViewTabs/WebViewTabBase.ts
index 62712d8..34eb4ee 100644
--- a/test/e2e/src/webViewTabs/WebViewTabBase.ts
+++ b/test/e2e/src/webViewTabs/WebViewTabBase.ts
@@ -1,5 +1,6 @@
 import { WebView } from "wdio-vscode-service";
 import { webViewUtils } from "../vscodeComponentsUtils/WebViewUtils.js";
+import allureReporter from '@wdio/allure-reporter';
 
 
 /**
@@ -21,6 +22,7 @@ export abstract class WebViewTabBase {
      * Switches to the webview tab.
      */
     public async switchTo() {
+        await allureReporter.addStep(`Switch to "${this.title}" webview`);
         this.webview = await webViewUtils.getWebView(this.title);
         await this.webview.open();
     }
@@ -29,10 +31,11 @@ export abstract class WebViewTabBase {
      * Switches back to the main view.
      */
     public async switchBack() {
+        await allureReporter.addStep('Switch back from webview');
         if (!this.webview) {
             throw new Error('WebView not opened. Call switchTo() first.');
         }
         await this.webview.close();
         this.webview = null;
     }
-}
\ No newline at end of file
+}
diff --git a/test/e2e/wdio.conf.ts b/test/e2e/wdio.conf.ts
index 3376690..7f9ece7 100644
--- a/test/e2e/wdio.conf.ts
+++ b/test/e2e/wdio.conf.ts
@@ -8,6 +8,38 @@ import video from 'wdio-video-reporter'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+function normalizeEnvValue(value: string): string {
+    const trimmed = value.trim();
+    const quote = trimmed[0];
+    if ((quote === '"' || quote === "'") && trimmed.endsWith(quote)) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+
+function loadLocalEnvFile() {
+    const envPath = path.join(__dirname, '.env');
+    if (!fs.existsSync(envPath)) {
+        return;
+    }
+
+    const lines = fs.readFileSync(envPath, 'utf-8').split(/\r?\n/);
+    for (const line of lines) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)?\s*$/);
+        if (!match) {
+            continue;
+        }
+
+        const [, key, rawValue = ''] = match;
+        process.env[key] ??= normalizeEnvValue(rawValue);
+    }
+}
+
+loadLocalEnvFile();
+
+const vscodeBrowserVersion = process.env.E2E_VSCODE_VERSION ?? '1.126.0';
+const e2eWorkspacePath = process.env.E2E_WORKSPACE_PATH ?? path.join(os.tmpdir(), 'cloudinary-vscode-e2e-workspace');
+
 export const config: WebdriverIO.Config = {
     //
     // ====================
@@ -61,10 +93,11 @@ export const config: WebdriverIO.Config = {
     //
     capabilities: [{
         browserName: 'vscode',
-        browserVersion: 'stable', // also possible: "insiders" or a specific version e.g. "1.80.0"
+        browserVersion: vscodeBrowserVersion, // also possible: "stable", "insiders", or a specific version
         'wdio:enforceWebDriverClassic': true,
         'wdio:vscodeOptions': {
             extensionPath: path.resolve(__dirname, '../../'),
+            workspacePath: e2eWorkspacePath,
             
             ...(process.env.CI && {
                 vscodeArgs: {
@@ -184,8 +217,8 @@ export const config: WebdriverIO.Config = {
      */
     onPrepare: function () {
         /**
-         * Write the Cloudinary credentials to the global config file.
-         * the file location is ~/.cloudinary/environments.json
+         * Write the Cloudinary credentials to a workspace-local config file so
+         * e2e runs do not overwrite the user's ~/.cloudinary/environments.json.
          */
         const cloudName = process.env.E2E_CLOUD;
         const apiKey = process.env.E2E_API_KEY;
@@ -196,7 +229,7 @@ export const config: WebdriverIO.Config = {
             );
         }
         
-        const cloudinaryDir = path.join(os.homedir(), '.cloudinary');
+        const cloudinaryDir = path.join(e2eWorkspacePath, '.cloudinary');
         fs.mkdirSync(cloudinaryDir, { recursive: true });
         const outPath = path.join(cloudinaryDir, 'environments.json');
         const environments = {
@@ -283,7 +316,7 @@ export const config: WebdriverIO.Config = {
      * @param {boolean} result.passed    true if test has passed, otherwise false
      * @param {object}  result.retries   information about spec related retries, e.g. `{ attempts: 0, limit: 0 }`
      */
-    afterTest: async function(test, context, { error, result, duration, passed, retries }) {
+    afterTest: async function(_test, _context, { error }) {
         if (error) {
             allureReporter.addAttachment('Screenshot', Buffer.from(await browser.takeScreenshot(), 'base64'), 'image/png');
             try {
@@ -296,8 +329,8 @@ export const config: WebdriverIO.Config = {
                 if (logs) {
                     allureReporter.addAttachment('Extension Logs', logs, 'text/plain');
                 }
-            } catch {
-                console.warn('Failed to get extension logs', error);
+            } catch (logError) {
+                console.warn('Failed to get extension logs', logError);
             }
         }
     },