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/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);
             }
         }
     },