@slycode/slycode 0.1.18 → 0.2.0

package/dist/store/skills/interactive-explainer/SKILL.md

@@ -1,557 +0,0 @@
----
-name: interactive-explainer
-version: 1.0.1
-updated: 2026-02-22
-description: This skill creates single-page interactive HTML explainers for any topic including code architecture, documentation, system design, user workflows, or conceptual explanations. The skill should be used when users ask for visual explanations, interactive documentation, architecture diagrams, tutorials, or "explain X visually". It produces beautiful, step-through HTML files with graphs, flowcharts, animations, and interactive elements that help viewers quickly understand complex topics.
----
-
-# Interactive Explainer
-
-This skill transforms complex topics into engaging, single-page HTML explainers with interactive visualizations, step-through navigation, and beautiful presentation.
-
-## When This Skill Applies
-
-Trigger this skill when the request involves:
-- "Explain X visually" or "create an interactive explanation"
-- "Make a visual guide for..." or "interactive documentation"
-- "Show me how X works" (when visual output is implied)
-- Architecture diagrams, system overviews, or flow explanations
-- User tutorials, onboarding guides, or walkthroughs
-- Any request for visual/interactive representation of concepts, code, or systems
-
-## Output Location
-
-All explainer files are created in: `documentation/interactive/`
-
-Create this directory if it doesn't exist. Name files descriptively:
-- `architecture_overview.html`
-- `message_flow_explained.html`
-- `sdk_quickstart_guide.html`
-
----
-
-## Workflow Overview
-
-```
-Phase 1: Discovery → Phase 2: Research → Phase 3: Design → Phase 4: Build → Phase 5: Polish
-```
-
-Execute each phase fully before proceeding to the next.
-
----
-
-## Phase 1: Discovery
-
-**Goal:** Understand exactly what needs to be explained and to whom.
-
-### 1.1 Classify the Content Type
-
-Determine the primary content type from the request:
-
-| Content Type | Indicators | Example Request |
-|--------------|------------|-----------------|
-| **Code Architecture** | File paths, classes, modules, "how does X work" | "Explain the SDK architecture" |
-| **Data/Message Flow** | Pipeline, flow, routing, "how data moves" | "Show message routing flow" |
-| **API Reference** | Endpoints, methods, parameters | "Interactive API docs" |
-| **User Workflow** | Tutorial, guide, "how to use" | "User guide for the chat app" |
-| **System Design** | Infrastructure, services, deployment | "Explain the server architecture" |
-| **Concept/Theory** | Abstract concepts, "what is X" | "Explain WebSocket protocol" |
-| **Comparison** | "vs", "compare", "differences" | "REST vs WebSocket comparison" |
-
-### 1.2 Identify the Audience
-
-Determine expertise level to calibrate depth:
-- **Beginner**: More context, simpler terms, guided progression
-- **Intermediate**: Technical terms okay, focus on patterns and flows
-- **Expert**: Deep dives, edge cases, implementation details
-
-### 1.3 Define Scope
-
-List the specific things that must be covered. Avoid scope creep.
-
----
-
-## Phase 2: Research
-
-**Goal:** Gather complete understanding of the topic before designing.
-
-### 2.1 For Code-Based Topics
-
-Read and understand ALL relevant code:
-
-```
-1. Identify entry points and main files
-2. Trace dependencies and imports
-3. Map relationships between components
-4. Note key functions/methods and their purposes
-5. Understand data structures and state
-6. Identify patterns and architectural decisions
-```
-
-**Critical:** Do not start building until the entire relevant codebase is understood. Read files thoroughly, not just skimming.
-
-### 2.2 For External Documentation
-
-Fetch and process reference materials:
-
-```
-1. Use WebFetch for external URLs
-2. Use Read for local documentation
-3. Extract key concepts and relationships
-4. Identify hierarchy of information
-5. Note examples and use cases
-```
-
-### 2.3 For Conceptual Topics
-
-Research through multiple angles:
-
-```
-1. Core definition and purpose
-2. Historical context if relevant
-3. Key components/parts
-4. How parts interact
-5. Common use cases
-6. Comparison to related concepts
-```
-
-### 2.4 Create Knowledge Map
-
-Before proceeding, create a mental model:
-- What are the main entities/concepts?
-- How do they relate to each other?
-- What is the flow/sequence of operations?
-- What are the key decision points?
-- What would surprise or confuse someone new?
-
----
-
-## Phase 3: Design
-
-**Goal:** Plan the structure and visualization approach.
-
-### 3.1 Select Primary Visualization Pattern
-
-Reference: `references/design_patterns.md`
-
-| Content Type | Primary Pattern | Secondary Options |
-|--------------|-----------------|-------------------|
-| Code Architecture | Component Network (vis.js) | Mermaid class diagrams |
-| Data/Message Flow | Animated Flow (CSS/GSAP) | Mermaid sequence diagrams |
-| API Reference | Interactive Reference | Tables + code blocks |
-| User Workflow | Step-Through Guide | Reveal.js style |
-| System Design | 3D Architecture (Three.js) | vis.js network |
-| Concept/Theory | Progressive Reveal | D3 hierarchy |
-| Comparison | Side-by-Side Matrix | Radar charts |
-
-### 3.2 Plan Sections
-
-Structure content into 5-7 logical sections:
-
-```
-1. Overview (always first)
-   - What is this?
-   - Why does it matter?
-   - Key terms
-
-2-5. Core Content Sections
-   - One major concept per section
-   - Build progressively
-   - Include visualizations
-
-6. Integration/Connections (if applicable)
-   - How parts connect
-   - External dependencies
-
-7. Summary/Quick Reference (always last)
-   - Key takeaways
-   - Quick reference card
-```
-
-### 3.3 Choose Supporting Visualizations
-
-For each section, determine:
-- Primary visualization (main focus)
-- Supporting elements (code blocks, tables, lists)
-- Interactive elements (click handlers, tooltips)
-
-Reference: `references/visualization_libraries.md`
-
-### 3.4 Design Data Structures
-
-Plan the JavaScript data structures needed:
-
-```javascript
-// Example: Component network data
-const components = [
-    { id: 'client', label: 'Client', type: 'frontend', description: '...' },
-    { id: 'server', label: 'Server', type: 'backend', description: '...' }
-];
-
-const connections = [
-    { from: 'client', to: 'server', label: 'HTTP/WebSocket' }
-];
-```
-
----
-
-## Phase 4: Build
-
-**Goal:** Create the HTML file with all content and visualizations.
-
-### 4.1 Use the Base Template
-
-Start with: `assets/base_template.html`
-
-The template provides:
-- All CDN library imports
-- Dark theme CSS variables
-- Navigation system
-- Section structure
-- Detail panel
-- Code copy functionality
-
-### 4.2 Customize the Template
-
-Replace placeholders:
-- `{{TITLE}}` - The explainer title
-- `{{SECTIONS}}` - The section content
-
-### 4.3 Build Each Section
-
-Section HTML structure:
-
-```html
-<section class="section" data-title="Section Name">
-    <div class="section-header">
-        <h1 class="section-title">Section Title</h1>
-        <p class="section-subtitle">Brief description of this section</p>
-    </div>
-
-    <!-- Main visualization -->
-    <div class="viz-container viz-full">
-        <!-- Visualization content -->
-    </div>
-
-    <!-- Supporting content -->
-    <div class="grid-2">
-        <div class="card">...</div>
-        <div class="card">...</div>
-    </div>
-</section>
-```
-
-### 4.4 Implement Visualizations
-
-#### Mermaid Diagrams
-
-**Critical: Mermaid in Hidden Sections**
-
-Mermaid cannot render into hidden elements (`display: none`). Since sections are hidden until navigated to, use:
-
-1. Set `startOnLoad: false` in mermaid.initialize()
-2. Manually call `mermaid.run()` when navigating to a section:
-
-```javascript
-// In goToSection function:
-const mermaidDivs = activeSection.querySelectorAll('.mermaid');
-mermaidDivs.forEach(el => {
-    if (el.querySelector('svg')) return; // Already rendered
-    const code = el.textContent;
-    el.innerHTML = code;
-    mermaid.run({ nodes: [el] });
-});
-```
-
-**Dark Theme Styling**
-
-Use dark fills with colored strokes for better theme integration (not bright solid fills):
-
-```html
-<pre class="mermaid">
-flowchart LR
-    A[Step 1] --> B[Step 2] --> C[Step 3]
-    style A fill:#1a3a4a,stroke:#00d4ff,stroke-width:2px,color:#00d4ff,rx:10,ry:10
-    style B fill:#1a3a3a,stroke:#4ecdc4,stroke-width:2px,color:#4ecdc4,rx:10,ry:10
-    style C fill:#1a2a1a,stroke:#2ecc71,stroke-width:2px,color:#2ecc71,rx:10,ry:10
-</pre>
-```
-
-**Scaling for Readability**
-
-Mermaid diagrams render small by default. Use CSS to scale:
-
-```css
-.mermaid-container {
-    display: flex;
-    justify-content: center;
-    align-items: center;
-    padding: 4rem 2rem;
-    min-height: 250px;
-}
-
-.mermaid-container .mermaid {
-    transform: scale(2.5);
-    transform-origin: center center;
-}
-
-/* Thicker arrows for visibility */
-.mermaid-container .mermaid .flowchart-link {
-    stroke-width: 3px !important;
-}
-```
-
-**Known Limitation**: Vertical text centering inside Mermaid nodes is not reliably controllable via CSS. The text positioning is handled internally by Mermaid's SVG generation.
-
-#### vis.js Network
-```html
-<div id="network1" class="network-container"></div>
-<script>
-    const nodes = new vis.DataSet([...]);
-    const edges = new vis.DataSet([...]);
-    new vis.Network(document.getElementById('network1'), {nodes, edges}, options);
-</script>
-```
-
-#### Chart.js
-
-**Critical**: Chart.js with `maintainAspectRatio: false` requires a fixed-height container, otherwise the chart grows infinitely and crashes the browser:
-
-```html
-<div style="position: relative; height: 300px; width: 100%;">
-    <canvas id="myChart"></canvas>
-</div>
-```
-
-#### Code Blocks
-```html
-<div class="code-block">
-    <div class="code-header">
-        <span class="code-filename">example.py</span>
-        <button class="code-copy">Copy</button>
-    </div>
-    <pre><code class="language-python">def example():
-    pass</code></pre>
-</div>
-```
-
-### 4.5 Add Interactivity
-
-**Click to Show Details:**
-```html
-<div class="card" data-detail onclick="showDetail('Title', 'Content HTML')">
-    ...
-</div>
-```
-
-**Hover Tooltips:**
-```javascript
-element.addEventListener('mouseenter', (e) => {
-    showTooltip(e.target.dataset.info, e.pageX, e.pageY);
-});
-```
-
-**Network Node Click:**
-```javascript
-network.on('click', function(params) {
-    if (params.nodes.length > 0) {
-        const nodeData = nodes.get(params.nodes[0]);
-        showDetail(nodeData.label, nodeData.description);
-    }
-});
-```
-
-### 4.6 Style Considerations
-
-- Use CSS variables for consistent theming
-- Maintain visual hierarchy with font sizes
-- Add subtle animations for engagement
-- Ensure text contrast meets accessibility standards
-- Test responsive breakpoints
-
----
-
-## Phase 5: Polish
-
-**Goal:** Refine and verify the final output.
-
-### 5.1 Content Review
-
-- [ ] All planned sections are present
-- [ ] Information is accurate and complete
-- [ ] Technical terms are explained or obvious
-- [ ] Examples are realistic and helpful
-- [ ] Flow is logical and progressive
-
-### 5.2 Visual Review
-
-- [ ] Visualizations render correctly
-- [ ] Colors are consistent with theme
-- [ ] Text is readable at all sizes
-- [ ] Animations are smooth, not jarring
-- [ ] Icons are relevant and helpful
-
-### 5.3 Interaction Review
-
-- [ ] Navigation works (buttons + keyboard)
-- [ ] All clickable elements respond
-- [ ] Detail panel opens/closes correctly
-- [ ] Code copy buttons work
-- [ ] No console errors
-
-### 5.4 Responsive Check
-
-Test layout at:
-- Desktop (1200px+)
-- Tablet (768px - 1024px)
-- Mobile (< 768px)
-
-### 5.5 Final Touches
-
-- Add favicon if appropriate
-- Verify all external CDN links work
-- Add print styles if needed
-- Consider adding a "last updated" date
-
----
-
-## Library Quick Reference
-
-### When to Use Each Library
-
-| Library | Best For | Complexity |
-|---------|----------|------------|
-| **Mermaid** | Quick flowcharts, sequence diagrams, ER diagrams | Low |
-| **vis.js** | Interactive network graphs, architecture diagrams | Medium |
-| **D3.js** | Custom data visualizations, hierarchies | High |
-| **Chart.js** | Standard charts (bar, line, pie, radar) | Low |
-| **Three.js** | 3D visualizations, spatial representations | High |
-| **GSAP** | Complex animations, scroll-triggered effects | Medium |
-| **Cytoscape.js** | Graph theory, network analysis | Medium |
-
-### CDN Links (All in Base Template)
-
-All libraries are pre-loaded in `assets/base_template.html`. No additional imports needed unless using specialized components.
-
----
-
-## Common Patterns
-
-### Architecture Overview Section
-
-```html
-<section class="section" data-title="Architecture">
-    <div class="section-header">
-        <h1 class="section-title">System Architecture</h1>
-        <p class="section-subtitle">How the components fit together</p>
-    </div>
-
-    <div class="viz-container viz-with-sidebar">
-        <div id="archNetwork" class="network-container"></div>
-        <div class="sidebar">
-            <h3>Components</h3>
-            <div id="componentList">
-                <!-- Populated dynamically -->
-            </div>
-        </div>
-    </div>
-</section>
-```
-
-### Data Flow Section
-
-```html
-<section class="section" data-title="Data Flow">
-    <div class="section-header">
-        <h1 class="section-title">Message Flow</h1>
-        <p class="section-subtitle">How data moves through the system</p>
-    </div>
-
-    <div class="viz-container viz-full">
-        <pre class="mermaid">
-        sequenceDiagram
-            participant C as Client
-            participant S as Server
-            participant D as Database
-            C->>S: Request
-            S->>D: Query
-            D-->>S: Results
-            S-->>C: Response
-        </pre>
-    </div>
-
-    <div class="grid-3">
-        <div class="card">
-            <div class="card-title"><i data-lucide="send"></i> Request</div>
-            <div class="card-content">Description of request phase</div>
-        </div>
-        <!-- More cards -->
-    </div>
-</section>
-```
-
-### Quick Reference Section
-
-```html
-<section class="section" data-title="Reference">
-    <div class="section-header">
-        <h1 class="section-title">Quick Reference</h1>
-        <p class="section-subtitle">Key information at a glance</p>
-    </div>
-
-    <table class="data-table">
-        <thead>
-            <tr>
-                <th>Component</th>
-                <th>Purpose</th>
-                <th>Key Methods</th>
-            </tr>
-        </thead>
-        <tbody>
-            <tr>
-                <td><span class="badge badge-primary">Client</span></td>
-                <td>Handles user interactions</td>
-                <td><code>connect()</code>, <code>send()</code></td>
-            </tr>
-        </tbody>
-    </table>
-</section>
-```
-
----
-
-## Quality Checklist
-
-Before delivering the explainer:
-
-### Content Quality
-- [ ] Topic is fully researched
-- [ ] All claims are accurate
-- [ ] Examples are realistic
-- [ ] Progression is logical
-
-### Visual Quality
-- [ ] Visualizations load and render
-- [ ] Colors follow the theme
-- [ ] Text is readable
-- [ ] Animations are smooth
-
-### Technical Quality
-- [ ] No console errors
-- [ ] All libraries load from CDN
-- [ ] Navigation works completely
-- [ ] Responsive at all breakpoints
-
-### User Experience
-- [ ] Can understand without prior knowledge (if beginner audience)
-- [ ] Interactive elements are discoverable
-- [ ] Information density is appropriate
-- [ ] Time to consume is reasonable
-
----
-
-## Resources
-
-- `references/visualization_libraries.md` - Detailed library documentation and examples
-- `references/design_patterns.md` - Patterns for different content types
-- `assets/base_template.html` - Starting template with all imports and base styling