feat: Template Browser Phase 3 - Usage Guidance & Context (#96) (#104)

* feat: Template Browser Phase 3 - Usage Guidance & Context (#96)

Adds contextual guidance fields to help users understand when and how to use each template:

**New Template Fields:**
- when_to_use: Brief description of ideal usage scenarios
- use_cases: Array of 2-4 specific example scenarios
- prerequisites: Knowledge or setup requirements
- related_templates: Template IDs for discovery and cross-linking
- estimated_time: Time to complete the template

**Changes:**
- Updated Template interface in TemplateTypes.ts with new optional guidance fields
- Added comprehensive guidance metadata to all 5 built-in templates in constants.ts
- Enhanced Template Browser UI with collapsible guidance sections
- Added CSS styling for guidance display (labels, lists, related templates, time badges)
- JavaScript toggle function for expanding/collapsing guidance sections

**Implementation Details:**
- Guidance section displays only when at least one guidance field is present
- Collapsible design with smooth toggle animation matching preview sections
- Visual hierarchy with icons for each guidance type (📌 When to Use, 💡 Use Cases, ✅ Prerequisites, 🔗 Related Templates)
- Time estimate badge displayed in toggle button header (⏱️)
- Related templates shown as clickable tags for future navigation
- Custom templates from JSON files can also include these guidance fields

Fixes #96

* fix: Address security and code quality issues in Template Browser

**Critical Security Fix:**
- Fixed XSS vulnerability in onclick handlers by replacing all inline event handlers with event delegation
- Replaced onclick="function('${templateId}')" pattern with data-command and data-* attributes
- Implemented single master event listener using event.target.closest('[data-command]')
- Template IDs and user-controllable data no longer executed as JavaScript code

**Code Quality Improvements:**
- Added validation warning for missing built-in template metadata
- Optimized CSS transition from 'all' to specific properties (background, color, border-color) for better performance
- Removed redundant justify-content CSS property (margin-left: auto already handles spacing)
- Refactored toggleGuidance() to use DOM traversal with nextElementSibling
- Refactored togglePreview() to accept button element and use classList.toggle with boolean
- Simplified logic using classList.toggle(class, boolean) instead of manual add/remove

**Event Delegation Changes:**
- Replaced 18+ onclick handlers with data-command attributes
- Added master click handler on document.body for all buttons
- Added event listener for search input
- Added modal overlay click handler with proper event target checking
- All functions now receive elements/parameters directly instead of reconstructing IDs

**Security Impact:**
Previously, a malicious template file named `');alert(1);('.json` could have executed arbitrary JavaScript. Now all user data is safely stored in data attributes and never executed.

Addresses code review feedback.

---------

Co-authored-by: Claude <[email protected]>

Author: jsonify

src/constants.ts

@@ -84,11 +84,81 @@ So that [benefit].
  * Built-in template metadata for display in picker
  */
 export const BUILT_IN_TEMPLATE_INFO = [
-    { label: 'Problem/Solution', value: 'problem-solution', description: 'Document bugs and troubleshooting' },
-    { label: 'Meeting', value: 'meeting', description: 'Organize meeting notes and action items' },
-    { label: 'Research', value: 'research', description: 'Structure your research and findings' },
-    { label: 'User Story', value: 'user-story', description: 'Agile user stories with tasks, criteria, and estimates' },
-    { label: 'Quick', value: 'quick', description: 'Simple dated note' }
+    {
+        label: 'Problem/Solution',
+        value: 'problem-solution',
+        description: 'Document bugs and troubleshooting',
+        when_to_use: 'When debugging issues, documenting solutions to problems, or troubleshooting technical challenges that you want to reference later.',
+        use_cases: [
+            'Debugging a production bug and documenting the fix',
+            'Troubleshooting a development environment issue',
+            'Recording solutions to recurring technical problems',
+            'Documenting workarounds for known issues'
+        ],
+        prerequisites: ['Basic understanding of the problem domain', 'Ability to describe technical issues clearly'],
+        related_templates: ['research', 'user-story'],
+        estimated_time: '5-10 minutes'
+    },
+    {
+        label: 'Meeting',
+        value: 'meeting',
+        description: 'Organize meeting notes and action items',
+        when_to_use: 'Perfect for team meetings, client calls, one-on-ones, or any discussion where you need to track attendees, agenda items, and action items.',
+        use_cases: [
+            'Daily standup or sprint planning meetings',
+            'Client requirement gathering sessions',
+            'Team retrospectives and brainstorming',
+            'One-on-one meetings with managers or teammates'
+        ],
+        prerequisites: ['Meeting agenda or topics to discuss'],
+        related_templates: ['user-story', 'research'],
+        estimated_time: '2-3 minutes setup, ongoing during meeting'
+    },
+    {
+        label: 'Research',
+        value: 'research',
+        description: 'Structure your research and findings',
+        when_to_use: 'Ideal for investigating new technologies, gathering information on topics, or conducting structured research with clear questions and findings.',
+        use_cases: [
+            'Evaluating new libraries or frameworks for a project',
+            'Researching solutions to architectural decisions',
+            'Learning about new programming concepts or patterns',
+            'Gathering competitive analysis or market research'
+        ],
+        prerequisites: ['Clear research topic or question', 'Basic research methodology understanding'],
+        related_templates: ['problem-solution'],
+        estimated_time: '5-15 minutes setup, extended for research'
+    },
+    {
+        label: 'User Story',
+        value: 'user-story',
+        description: 'Agile user stories with tasks, criteria, and estimates',
+        when_to_use: 'Use when planning features in agile/scrum workflows, breaking down requirements into user-focused stories with clear acceptance criteria.',
+        use_cases: [
+            'Sprint planning and backlog grooming',
+            'Feature requirement documentation',
+            'Breaking down epics into implementable stories',
+            'Tracking development tasks with clear success criteria'
+        ],
+        prerequisites: ['Understanding of agile user story format', 'Knowledge of the feature or requirement'],
+        related_templates: ['meeting', 'problem-solution'],
+        estimated_time: '10-15 minutes'
+    },
+    {
+        label: 'Quick',
+        value: 'quick',
+        description: 'Simple dated note',
+        when_to_use: 'For rapid note-taking when you need minimal structure, such as jotting down ideas, temporary notes, or quick reminders.',
+        use_cases: [
+            'Capturing quick thoughts or ideas',
+            'Temporary notes during phone calls',
+            'Daily journal or stream-of-consciousness writing',
+            'Scratch pad for calculations or brainstorming'
+        ],
+        prerequisites: [],
+        related_templates: ['meeting', 'research'],
+        estimated_time: 'Under 1 minute'
+    }
 ];
 
 /**

src/templates/TemplateTypes.ts

@@ -57,6 +57,13 @@ export interface Template {
     created?: string;
     modified?: string;
     usage_count?: number;
+
+    // Usage guidance (Phase 3)
+    when_to_use?: string;           // Brief 1-2 sentence description of ideal usage scenarios
+    use_cases?: string[];           // Array of 2-4 specific scenarios
+    prerequisites?: string[];       // Knowledge or setup requirements
+    related_templates?: string[];   // Template IDs for discovery and cross-linking
+    estimated_time?: string;        // Time to complete (e.g., "2-3 minutes")
 }
 
 /**