chore: improved marketplace docs

.vscodeignore

@@ -41,6 +41,7 @@ reinstall.sh
 docs/**
 *.md
 !README.md
+!MARKETPLACE_README.md
 !LICENSE
 !LICENSE.pro
 !EULA.md

CLEANUP_SUMMARY.md

@@ -123,3 +123,4 @@ Consider these additional cleanup actions:
 **VSIX Files Organized**: 3 old releases moved to `releases/`
 
 
+

MARKETPLACE_README.md

@@ -0,0 +1,155 @@
+# DevBuddy for VS Code
+### Unified ticket management for Linear and Jira — directly inside VS Code
+
+[![Version](https://img.shields.io/visual-studio-marketplace/v/angelogirardi.dev-buddy)](https://marketplace.visualstudio.com/items?itemName=angelogirardi.dev-buddy)
+[![Installs](https://img.shields.io/visual-studio-marketplace/i/angelogirardi.dev-buddy)](https://marketplace.visualstudio.com/items?itemName=angelogirardi.dev-buddy)
+[![Rating](https://img.shields.io/visual-studio-marketplace/stars/angelogirardi.dev-buddy)](https://marketplace.visualstudio.com/items?itemName=angelogirardi.dev-buddy)
+
+## Work Faster with Your Issues Inside VS Code
+
+DevBuddy brings your tickets into a single sidebar so you can browse, create, update, and work on issues without switching to the browser.
+
+![DevBuddy Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/start_ticket_branch.gif)
+
+## Key Features
+
+| Feature | Description | Platforms |
+|---------|-------------|-----------|
+| **Unified Issue Explorer** | View and manage all tickets from VS Code | Linear, Jira Cloud, Jira Server (beta) |
+| **TODO Converter** | Convert TODOs to tickets with automatic code permalinks | Linear, Jira Cloud |
+| **AI Workflows** | Generate PR summaries and standups automatically | Linear, Jira Cloud |
+| **Branch Integration** | Create and manage branches directly from tickets | Linear, Jira Cloud |
+| **Chat Participant** | Ask `@devbuddy` questions in natural language | Linear |
+| **Monorepo Support** | Intelligent package detection and validation | All platforms |
+
+## Quick Start
+
+1. **Install DevBuddy** from the VS Code Marketplace
+2. **Open the DevBuddy sidebar** (click the checklist icon)
+3. **Connect your platform:**
+   - Linear: `DevBuddy: Update Linear API Key`
+   - Jira Cloud: `DevBuddy: Setup Jira Cloud`
+4. **Start managing issues** directly inside VS Code
+
+Full documentation: [DevBuddy Quick Start Guide](https://github.com/angelo-hub/devbuddy/blob/main/docs/user-guides/QUICKSTART.md)
+
+## Example Workflows
+
+### Convert TODO → Ticket
+
+![TODO Converter Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/todo-converter-demo.gif)
+
+Write a TODO comment, right-click → "Convert TODO to Ticket". DevBuddy automatically:
+- Creates a ticket with file path and line number
+- Generates GitHub/GitLab/Bitbucket permalink to exact code location
+- Includes 5 lines of surrounding code context
+- Links to current branch and commit SHA
+
+### Create a Branch from an Issue
+
+![Branch Creation Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/start_ticket_branch.gif)
+
+Right-click any ticket → "Start Branch for Ticket". DevBuddy creates a branch with smart naming (conventional, simple, or custom) and automatically associates it with the ticket.
+
+### Edit Tickets Directly in VS Code
+
+![Edit Ticket Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/edit_ticket.gif)
+
+Click any ticket to view full details, update status, add comments, and manage all ticket properties without leaving your editor.
+
+### AI-Powered Standup Generator
+
+![Standup Builder Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/standup_builder.gif)
+
+Run `DevBuddy: Generate Standup Update` to automatically generate standup reports from your commits and ticket activity with:
+- Yesterday's completed work
+- Today's planned tasks
+- Blockers and dependencies
+- Automatic ticket linking
+
+## Supported Platforms
+
+### Fully Supported
+- **Linear** - Complete feature set with AI integration
+- **Jira Cloud** - Full feature parity with Linear
+
+### In Beta
+- **Jira Server / Data Center** - Read-only support (editing coming soon)
+
+## Optional AI Enhancements
+
+Connect GitHub Copilot or another LLM provider to unlock:
+- Pull request summaries
+- Standup reports
+- Ticket drafts with descriptions and acceptance criteria
+
+**AI features are optional** — DevBuddy works fully without them using intelligent rule-based analysis.
+
+## Privacy and Security
+
+- ✅ All credentials stored using VS Code Secret Storage
+- ✅ No telemetry collected
+- ✅ DevBuddy doesn't run servers or proxy your data
+- ✅ Only Jira/Linear APIs you configure are contacted
+- ✅ Privacy-first: AI is completely optional
+
+## What's New in v0.5.0
+
+- **Jira Server/Data Center Support (Beta)** - Connect to self-hosted Jira instances
+- **Enhanced TODO Converter** - Better permalink generation and multi-file workflows
+- **Improved AI Models** - Support for GPT-4o, GPT-4.1, and Gemini 2.0 Flash
+- **Better Error Handling** - Clearer error messages and debugging support
+- **Runtime Validation** - Production-grade API validation with Zod v4
+
+## Commands Overview
+
+### Universal Commands (All Platforms)
+- `DevBuddy: Refresh Tickets` - Reload ticket list
+- `DevBuddy: Create Ticket` - Open ticket creation form
+- `DevBuddy: Generate PR Summary` - Generate PR description
+- `DevBuddy: Generate Standup Update` - Generate standup report
+
+### Platform-Specific Setup
+- `DevBuddy: Update Linear API Key` - Configure Linear
+- `DevBuddy: Setup Jira Cloud` - Configure Jira Cloud
+- `DevBuddy: Setup Jira Server` - Configure Jira Server/Data Center
+
+## Roadmap
+
+- ✅ Linear - Full support
+- ✅ Jira Cloud - Full support
+- 🚧 Jira Server/Data Center - Beta (editing coming soon)
+- ⏳ GitHub Issues integration
+- ⏳ YouTrack support
+- ⏳ Monday.com integration
+- ⏳ Enhanced multi-account workflows
+
+Track updates: [GitHub Repository](https://github.com/angelo-hub/devbuddy)
+
+## Documentation
+
+- [Quick Start Guide](https://github.com/angelo-hub/devbuddy/blob/main/docs/user-guides/QUICKSTART.md)
+- [Complete Linear Guide](https://github.com/angelo-hub/devbuddy/blob/main/docs/user-guides/LINEAR_BUDDY_GUIDE.md)
+- [Jira Cloud Setup](https://github.com/angelo-hub/devbuddy/blob/main/JIRA_QUICK_START.md)
+- [Feature Compatibility Matrix](https://github.com/angelo-hub/devbuddy/blob/main/FEATURE_COMPATIBILITY_MATRIX.md)
+- [Full Documentation](https://github.com/angelo-hub/devbuddy)
+
+## Support
+
+**Documentation:** [github.com/angelo-hub/devbuddy](https://github.com/angelo-hub/devbuddy)  
+**Issues & Feature Requests:** [GitHub Issues](https://github.com/angelo-hub/devbuddy/issues)
+
+If DevBuddy improves your workflow, please consider leaving a review or starring the repository! ⭐
+
+## License
+
+**Dual License:**
+- **Core Features:** MIT License - Free and open source
+- **Pro Features:** Commercial License (when available)
+
+All current features are free to use. Future Pro features will require a subscription.
+
+---
+
+**Version 0.5.0** | Made with ❤️ for developers who hate context switching
+

media/walkthrough/MEDIA_PLACEHOLDERS_GUIDE.md

@@ -333,23 +333,20 @@ Once media is created:
 
 ## Current Status
 
-### Created
-- ✅ Markdown with placeholders
-- ✅ Scripts for each demo
-- ✅ Directory structure
-
-### TODO
-- ⬜ Record: todo-converter-demo.gif
-- ⬜ Record: permalink-in-linear.gif  
-- ⬜ Record: add-more-todos.gif (KEY FEATURE)
-- ⬜ Record: basic-conversion.gif
-- ⬜ Record: link-existing-todos.gif
-- ⬜ Record: workflow-comparison.gif
-- ⬜ Record: real-world-example.mp4
-- ⬜ Add voiceover to MP4
-- ⬜ Optimize all files
-- ⬜ Update markdown with actual file references
-- ⬜ Test in VS Code walkthrough
+### ✅ Completed (Ready to Use)
+- ✅ `todo-converter-demo.gif` - Complete TODO workflow
+- ✅ `start_ticket_branch.gif` - Branch creation from ticket
+- ✅ `edit_ticket.gif` - Ticket editing and management
+- ✅ `standup_builder.gif` - AI standup generation
+
+### ⏳ Still TODO (Lower Priority)
+- ⏳ `pr-summary-demo.gif` - PR summary with monorepo detection
+- ⏳ `add-more-todos.gif` - Multi-file TODO workflow (KEY FEATURE)
+- ⏳ `jira-sidebar-demo.gif` - Jira platform demo
+- ⏳ `permalink-in-linear.gif` - Permalink click-through demo
+- ⏳ `link-existing-todos.gif` - Link existing TODOs feature
+- ⏳ `workflow-comparison.gif` - Old way vs new way comparison
+- ⏳ `real-world-example.mp4` - Narrated complete example
 
 ---
 

media/walkthrough/TODO_GIFS.md

@@ -1,45 +1,53 @@
-# Walkthrough GIFs TODO
+# Walkthrough GIFs Status
 
 ## Overview
-Currently all walkthrough steps use markdown files for media. Once we record GIFs, we should replace the markdown with GIFs for a better visual experience.
-
-## GIFs to Record
-
-### High Priority (Best Visual Impact)
-
-1. **`sidebar-demo.gif`** - For step `explore.sidebar`
-   - Show: Opening DevBuddy sidebar, viewing tickets organized by status, clicking a ticket
-   - Current: Uses `sidebar.md`
-   - Impact: HIGH - First visual of the product
-
-2. **`todo-converter-demo.gif`** - For step `feature.todoconverter`
-   - Show: Hovering over a TODO comment, clicking "Convert to Linear Ticket", showing the created ticket with permalink
-   - Current: Uses `todo-converter.md`
-   - Impact: HIGH - Unique feature showcase
-
-3. **`standup-demo.gif`** - For step `feature.standup`
-   - Show: Opening standup builder, selecting tickets, AI generating the standup update, copying result
-   - Current: Uses `standup.md`
-   - Impact: HIGH - AI feature showcase
-
-### Medium Priority
-
-4. **`pr-summary-demo.gif`** - For step `feature.prsummary`
-   - Show: Running PR summary command, showing monorepo detection, AI analysis, final summary
-   - Current: Uses `pr-summary.md`
-   - Impact: MEDIUM - AI feature showcase
-
-5. **`linear-sidebar-demo.gif`** - For step `feature.branches`
-   - Show: Clicking branch icon on a ticket, selecting source branch, reviewing generated name, branch created
-   - Current: Uses `branches.md`
-   - Impact: MEDIUM - Linear-specific feature
-
-### Lower Priority (Text is Sufficient)
-
-6. **`status-update-demo.gif`** - For step `feature.status`
-   - Show: Right-clicking a ticket, selecting "Update Status", choosing new status with visual indicators
-   - Current: Uses `status.md`
-   - Impact: LOW - Simple interaction
+We now have 4 key GIFs recorded! These provide visual demonstrations of DevBuddy's core features.
+
+## ✅ Completed GIFs
+
+### 1. **`todo-converter-demo.gif`** - TODO Converter
+   - **Status:** ✅ COMPLETE
+   - **Shows:** Complete TODO to ticket conversion workflow with permalink generation
+   - **Used in:** Marketplace README, Walkthrough, Documentation
+   - **Impact:** HIGH - Shows unique feature
+
+### 2. **`start_ticket_branch.gif`** - Branch Creation
+   - **Status:** ✅ COMPLETE
+   - **Shows:** Creating a branch from a ticket in the sidebar, branch naming options
+   - **Used in:** Marketplace README (hero demo), Walkthrough
+   - **Impact:** HIGH - Shows core workflow
+
+### 3. **`edit_ticket.gif`** - Ticket Editing
+   - **Status:** ✅ COMPLETE
+   - **Shows:** Viewing and editing ticket details, updating status, adding comments
+   - **Used in:** Marketplace README, Walkthrough
+   - **Impact:** MEDIUM - Shows ticket management capabilities
+
+### 4. **`standup_builder.gif`** - AI Standup Generator
+   - **Status:** ✅ COMPLETE
+   - **Shows:** Opening standup builder, AI generating standup from commits and tickets
+   - **Used in:** Marketplace README, Walkthrough
+   - **Impact:** HIGH - Shows AI features
+
+## 📋 Still Needed (Lower Priority)
+
+### 5. **`pr-summary-demo.gif`** - PR Summary with Monorepo
+   - **Status:** ⏳ TODO
+   - **Shows:** Running PR summary command, monorepo package detection, AI analysis
+   - **Impact:** MEDIUM - Shows AI + monorepo features
+   - **Note:** Can use standup_builder.gif as temporary alternative
+
+### 6. **`add-more-todos.gif`** - Multi-File TODO Workflow  
+   - **Status:** ⏳ TODO
+   - **Shows:** Using "Add More TODOs" to link same ticket across multiple files
+   - **Impact:** HIGH - Key differentiator feature
+   - **Note:** This is the #1 priority for next recording session
+
+### 7. **`jira-sidebar-demo.gif`** - Jira Integration
+   - **Status:** ⏳ TODO
+   - **Shows:** DevBuddy sidebar with Jira issues, platform switching
+   - **Impact:** MEDIUM - Shows multi-platform support
+   - **Note:** Can use start_ticket_branch.gif temporarily
 
 ## Implementation Steps
 

media/walkthrough/branches.md

@@ -1,5 +1,7 @@
 # Smart Branch Creation
 
+![Start Ticket Branch Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/start_ticket_branch.gif)
+
 Linear Buddy makes it easy to create well-named, conventional branches directly from your tickets.
 
 ## How It Works

media/walkthrough/sidebar.md

@@ -1,5 +1,7 @@
 # Your Ticket Sidebar
 
+![DevBuddy Sidebar Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/start_ticket_branch.gif)
+
 The DevBuddy sidebar is your command center for multi-platform ticket management. It shows all your assigned tickets organized by workflow status.
 
 ## Universal Sidebar

media/walkthrough/standup.md

@@ -1,8 +1,8 @@
 # Generate Standup Updates
 
-Let AI generate your standup update automatically from your commits and Linear activity. No more scrambling to remember what you did.
+![Standup Builder Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/standup_builder.gif)
 
-![Standup Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/standup-demo.gif)
+Let AI generate your standup update automatically from your commits and Linear activity. No more scrambling to remember what you did.
 
 ## How It Works
 

media/walkthrough/status.md

@@ -1,5 +1,7 @@
 # Update Ticket Status
 
+![Edit Ticket Demo](https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/edit_ticket.gif)
+
 Keep your Linear board up-to-date without leaving VS Code. Change ticket status with a single click!
 
 ## How to Change Status

media/walkthrough/videos/README.md

@@ -37,7 +37,10 @@ This directory contains large media files (GIFs, MP4s) for documentation and wal
 
 | File | Size | Description | GitHub URL |
 |------|------|-------------|------------|
-| `todo-converter-demo.gif` | 12 MB | Complete TODO to ticket conversion workflow | `https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/todo-converter-demo.gif` |
+| `todo-converter-demo.gif` | ~12 MB | Complete TODO to ticket conversion workflow | `https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/todo-converter-demo.gif` |
+| `start_ticket_branch.gif` | ~12 MB | Creating a branch from a ticket in the sidebar | `https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/start_ticket_branch.gif` |
+| `edit_ticket.gif` | ~10 MB | Editing ticket details directly in VS Code | `https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/edit_ticket.gif` |
+| `standup_builder.gif` | ~15 MB | AI-powered standup generation from commits and tickets | `https://raw.githubusercontent.com/angelo-hub/devbuddy/main/media/walkthrough/videos/standup_builder.gif` |
 
 ## Adding New Videos
 

package.json

@@ -5,6 +5,7 @@
   "version": "0.5.0",
   "publisher": "angelogirardi",
   "license": "SEE LICENSE IN LICENSE",
+  "readme": "MARKETPLACE_README.md",
   "icon": "resources/icon.png",
   "author": {
     "name": "Angelo Girardi",