Feature/telemetry feedback rating clean

.gitignore

@@ -137,6 +137,24 @@ custom_fix.txt
 *-example.yml
 *_patch.txt
 
+# Working/analysis files
+BRANCH_*.md
+*_ISSUES_*.md
+*_DEBUGGING_*.md
+*_FIX.md
+*_IMPROVEMENT_*.md
+PR-*.md
+!.github/pull_request_template.md
+PR_DESCRIPTION.md
+
+# Test data files in lib/
+lib/collections.yaml
+lib/ratings.json
+
+# Spec working directories
+.kiro/specs/*/IMPLEMENTATION_PLAN.md
+.kiro/specs/*/PROGRESS.md
+
 # Shell scripts for debugging/fixing (keep only essential ones)
 add_metadata_to_tests.sh
 simple_metadata_fix.sh

docs/README.md

@@ -11,6 +11,7 @@ Marketplace and registry for Copilot prompt bundles in VS Code.
 - **[Repository Installation](user-guide/repository-installation.md)** — Team-shared configurations via Git
 - **[Sources](user-guide/sources.md)** — Managing bundle sources
 - **[Profiles and Hubs](user-guide/profiles-and-hubs.md)** — Profile and Hub management
+- **[Engagement](user-guide/engagement.md)** — Ratings, voting, and feedback
 - **[Configuration](user-guide/configuration.md)** — Extension settings
 - **[Troubleshooting](user-guide/troubleshooting.md)** — Common issues
 

docs/assets/compute-ratings.yml

@@ -0,0 +1,81 @@
+# Compute Ratings Workflow for Hub Repositories
+#
+# This GitHub Action computes ratings from GitHub Discussion reactions
+# and feedback comments. It should be added to your hub repository,
+# NOT to the prompt-registry extension repository.
+#
+# Prerequisites:
+# 1. Enable GitHub Discussions on your repository
+# 2. Create a collections.yaml mapping bundles to discussions
+# 3. Install @prompt-registry/lib package (or use npx)
+#
+# See: https://github.com/wherka-ama/prompt-registry/blob/main/docs/user-guide/engagement.md
+
+name: Compute Ratings
+
+on:
+  schedule:
+    # Run daily at 2:00 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+    inputs:
+      config_path:
+        description: 'Path to collections.yaml config file'
+        required: false
+        default: 'collections.yaml'
+      output_path:
+        description: 'Path for ratings.json output'
+        required: false
+        default: 'ratings.json'
+
+permissions:
+  contents: write
+  discussions: read
+
+jobs:
+  compute-ratings:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compile TypeScript
+        run: npm run compile
+
+      - name: Compute ratings
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          npx --package @prompt-registry/collection-scripts compute-ratings \
+            --config "${{ github.event.inputs.config_path || 'collections.yaml' }}" \
+            --output "${{ github.event.inputs.output_path || 'ratings.json' }}"
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet ratings.json 2>/dev/null; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push ratings
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add ratings.json
+          git commit -m "chore: update ratings.json [skip ci]"
+          git push

docs/contributor-guide/architecture/ui-components.md

@@ -8,14 +8,37 @@ WebView-based marketplace with tiles, search, and filters.
 
 ```mermaid
 graph TD
-    A["Webview (HTML/JS)<br/>Search | Filters | Bundle Tiles"] 
+    A["Webview (HTML/JS/CSS)<br/>Search | Filters | Bundle Tiles"] 
     B["MarketplaceViewProvider<br/>(TypeScript)"]
     C["RegistryManager"]
 
     A -->|postMessage| B
     B --> C
 ```
 
+### File Structure
+
+Webview assets are externalized for maintainability and CSP compliance:
+
+```
+src/ui/webview/
+├── marketplace/
+│   ├── marketplace.html    # HTML template with placeholders
+│   ├── marketplace.css     # Styles
+│   └── marketplace.js      # Client-side logic (IIFE pattern)
+├── bundleDetails/
+│   ├── bundleDetails.html  # HTML template with placeholders
+│   ├── bundleDetails.css   # Styles
+│   └── bundleDetails.js    # Client-side logic (IIFE pattern)
+└── shared/                 # Shared assets (if any)
+```
+
+**Key patterns:**
+- **HTML templates** use `{{placeholder}}` syntax replaced at runtime by TypeScript
+- **JavaScript** uses IIFE pattern with event delegation for CSP compliance
+- **No inline event handlers** — use `data-action` attributes instead of `onclick`
+- **Nonce-based CSP** — all `<script>` tags require `nonce="{{nonce}}"`
+
 ### Message Types
 
 | Message | Direction | Purpose |
@@ -31,6 +54,7 @@ graph TD
 | `getVersions` | Webview → Host | Get available versions |
 | `toggleAutoUpdate` | Webview → Host | Toggle auto-update |
 | `openSourceRepository` | Webview → Host | Open source repo |
+| `feedback` | Webview → Host | Open unified feedback dialog |
 
 ### Interaction Flow
 

docs/plans/2026-02-21-engagement-ux-resilience-design.md

@@ -0,0 +1,202 @@
+# Engagement UX & Resilience Design
+
+**Date**: 2026-02-21
+**Source**: [Issue #98](https://github.com/AmadeusITGroup/prompt-registry/issues/98) (last 2 comments)
+**Branch**: `feature/telemetry-feedback-rating-clean`
+
+## Scope
+
+This design covers:
+- Network resilience for feedback submission (Problem 2)
+- Immediate rating visibility after submission (Problem 1)
+- UX improvements: interactive stars, sort fix, confidence removal, zero-rating consistency, report/request links, feedback modal fix
+
+**Deferred**: Reactive rating single workflow, telemetry (VS Code ecosystem integration).
+
+---
+
+## 1. Network Resilience (Problem 2)
+
+### Decision: Wait for GitHub acknowledgement + local save with manual retry
+
+### Submission Flow
+
+1. User submits rating + feedback via interactive stars
+2. Extension calls GitHub API with configurable timeout (default: 10s)
+3. **On success**: Show confirmation, save locally with `synced: true`
+4. **On timeout/error**: Show error ("Feedback saved locally. Retry from the bundle menu when connectivity is restored."), save locally with `synced: false`
+5. User can retry unsynced feedback via context menu action ("Retry feedback submission")
+
+### Local Storage
+
+Extend `EngagementStorage` with `pending-feedback.json`:
+
+```typescript
+interface PendingFeedback {
+  bundleId: string;
+  sourceId: string;
+  hubId: string;
+  rating: RatingScore;  // 1-5
+  comment?: string;
+  timestamp: string;
+  synced: boolean;
+}
+```
+
+### Files to Modify
+
+- `src/storage/EngagementStorage.ts` — add pending feedback CRUD
+- `src/services/engagement/EngagementService.ts` — save locally on submit, update sync status
+- `src/services/engagement/backends/GitHubDiscussionsBackend.ts` — explicit timeout handling
+- `src/commands/FeedbackCommands.ts` — error messaging, retry action
+
+---
+
+## 2. Immediate Rating Visibility (Problem 1)
+
+### Decision: Client-side optimistic update, silently overwritten on next ratings.json fetch
+
+### Flow
+
+1. After submission (regardless of sync success), read current rating from `RatingCache`
+2. Compute new average: `(currentAvg * voteCount + userRating) / (voteCount + 1)`
+3. Store optimistic entry in `RatingCache` marked as `optimistic: true`
+4. Fire cache update event — UI refreshes immediately
+5. When next `ratings.json` fetch occurs, silently overwrite optimistic values
+
+### Data Model
+
+```typescript
+interface OptimisticRating {
+  bundleKey: string;      // sourceId:bundleId
+  userRating: RatingScore;
+  computedStarRating: number;
+  computedVoteCount: number;
+}
+```
+
+### Files to Modify
+
+- `src/services/engagement/RatingCache.ts` — add optimistic entry support, overwrite on refresh
+- `src/services/engagement/RatingService.ts` — clear optimistic entries on fetch
+- `src/commands/FeedbackCommands.ts` — trigger optimistic update after submission
+
+---
+
+## 3. Interactive Stars (Hover + Click)
+
+### Decision: Hover preview with click confirm, then comment field appears
+
+### Behavior
+
+- **Default state**: Filled/empty stars based on current rating (read-only appearance)
+- **On hover**: Stars highlight progressively (1-5) as cursor moves across
+- **On click**: Rating confirmed, comment text field slides open below with "Submit" button
+- **On submit**: Triggers feedback flow (section 1 above)
+- **No ratings**: Show nothing (no stars, no placeholder)
+- **Already rated**: Show user's rating with visual indicator (different color or "Your rating" tooltip)
+
+### Scope
+
+- **Marketplace webview**: Full interactive implementation
+- **TreeView**: Remains display-only (`★ 4.2 (42)`)
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — interactive star component
+- `src/ui/webview/marketplace/marketplace.css` — hover/active styles
+- `src/ui/MarketplaceViewProvider.ts` — handle new message types from webview
+- `src/commands/FeedbackCommands.ts` — accept submissions from webview
+
+---
+
+## 4. Remove Confidence Display
+
+Remove confidence text from rating display. Keep vote count.
+
+- Before: `★ 4.2 (42 votes, high confidence)`
+- After: `★ 4.2 (42)`
+
+Confidence data remains in `ratings.json` but is not shown in UI.
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — remove confidence from rating badge
+- `src/ui/MarketplaceViewProvider.ts` — remove confidence from TreeView tooltip
+
+---
+
+## 5. Fix Rating Sort
+
+### Decision: Sort by `starRating` first, `voteCount` as tiebreaker
+
+```javascript
+case 'rating-desc':
+    filteredBundles.sort((a, b) => {
+        const ratingA = a.rating?.starRating ?? 0;
+        const ratingB = b.rating?.starRating ?? 0;
+        if (ratingB !== ratingA) return ratingB - ratingA;
+        return (b.rating?.voteCount ?? 0) - (a.rating?.voteCount ?? 0);
+    });
+    break;
+case 'rating-asc':
+    filteredBundles.sort((a, b) => {
+        const ratingA = a.rating?.starRating ?? 0;
+        const ratingB = b.rating?.starRating ?? 0;
+        if (ratingA !== ratingB) return ratingA - ratingB;
+        return (a.rating?.voteCount ?? 0) - (b.rating?.voteCount ?? 0);
+    });
+    break;
+```
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — update sort comparators
+
+---
+
+## 6. Fix Feedback Modal
+
+Fix the existing modal triggered by clicking stars to properly display comments and rating breakdown. Data is already cached in `FeedbackCache` — the issue is rendering, not data fetching.
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — fix modal rendering
+- `src/ui/MarketplaceViewProvider.ts` — verify data passed to webview
+
+---
+
+## 7. Zero Rating Consistency
+
+- **No ratings at all**: Show nothing (no stars, no badge, no text)
+- **Has ratings but low**: Show actual star rating (e.g., `★ 1.2 (3)`)
+- Eliminate any display of "0 stars" or empty star rows for rated bundles
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — conditional rendering
+- `src/ui/RegistryTreeProvider.ts` — conditional rating display
+
+---
+
+## 8. Report Issue / Request Feature Links
+
+Add two separate links ("Report Issue", "Request Feature") in:
+- Bundle detail panel in the Marketplace webview
+- Right-click context menu on bundles in TreeView and Marketplace
+
+Links point to the bundle's source repository issues page (derived from adapter source URL).
+
+### Files to Modify
+
+- `src/ui/webview/marketplace/marketplace.js` — add links to detail panel
+- `src/ui/RegistryTreeProvider.ts` — add context menu items
+- `src/commands/` — new command handlers for opening issue/feature URLs
+- `package.json` — register new commands and menu contributions
+
+---
+
+## Deferred Items
+
+- **Reactive rating with single workflow**: Redesign of compute-ratings pipeline with single inbox discussion
+- **Telemetry**: VS Code telemetry ecosystem integration, separate config section