@dzhechkov/keysarium 1.4.0 → 1.5.0

package/templates/.claude/skills/edu-site-generator/modules/00-content-analysis.md

@@ -0,0 +1,84 @@
+# Step 0: Content Analysis
+
+## Goal
+Parse source documentation and extract distinct teachable topics.
+
+## Protocol
+
+1. **Identify input type:**
+   - URL(s) → use WebFetch to retrieve content
+   - Local path(s) → use Read tool
+   - Pasted text → use directly
+   - Topic description → generate content from knowledge
+
+2. **Extract topics:**
+   - Read through all source material
+   - Identify distinct concepts/practices/techniques
+   - Group related content into logical units
+   - Each unit = one potential section
+
+3. **For each topic, capture:**
+   - Title (concise, 3-8 words)
+   - Description (1 sentence)
+   - Key concepts (3-5 bullet points)
+   - Practical value (why learn this?)
+   - Content depth estimate (shallow/medium/deep)
+
+4. **Determine language:**
+   - Auto-detect from source content
+   - If mixed, ask user preference
+   - All UI text must match chosen language
+
+5. **Estimate scope:**
+   - Count topics → section count
+   - If < 3: warn user, suggest adding more content
+   - If > 20: suggest grouping or splitting into multiple courses
+   - Sweet spot: 5-15 sections
+
+## Output Format
+
+```javascript
+// Topic analysis result
+{
+  language: 'ru' | 'en',
+  courseTitle: 'string',
+  courseDescription: 'string',
+  topics: [
+    {
+      title: 'string',
+      description: 'string',
+      keyConcepts: ['string'],
+      depth: 'shallow' | 'medium' | 'deep',
+      suggestedExercise: 'quiz' | 'flashcards' | 'matching' | 'drag-order' | 'builder' | 'scenario'
+    }
+  ]
+}
+```
+
+## Exercise Type Heuristics
+
+| Content Nature | Best Exercise Type | `interactiveType` value |
+|---------------|-------------------|------------------------|
+| Definitions, terms, concepts | Flashcards | `'flashcards'` |
+| Comparisons, mappings, associations | Matching | `'matching'` |
+| Factual knowledge, best practices | Quiz | `'quiz'` |
+| Sequential processes, ordered steps | Drag-to-Order | `'drag-and-drop'` |
+| Command syntax, API calls | Command Builder | `'builder'` |
+| Decision-making, workflows | Scenario Game | `'scenario'` |
+
+**IMPORTANT:** Use ONLY these exact `interactiveType` values. Do NOT use `'drag-order'`, `'ordering'`, or `'simulation'` — they are legacy aliases.
+
+## Checkpoint
+
+```
+Step 0/7: Content Analysis Complete
+Topics: N identified
+Language: {language}
+Course: "{courseTitle}"
+
+Topic list:
+1. {title} — {suggestedExercise}
+...
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/01-course-structure.md

@@ -0,0 +1,75 @@
+# Step 1: Course Structure
+
+## Goal
+Transform analyzed topics into a structured course with section definitions and exercise assignments.
+
+## Protocol
+
+1. **Order sections** from foundational to advanced:
+   - Basic concepts first
+   - Build on prior knowledge
+   - End with synthesis/integration topics
+
+2. **Assign exercise types** per section:
+   - Read `references/exercise-catalog.md` for guidance
+   - Vary types to avoid monotony (no 3+ consecutive same type)
+   - Match exercise to content nature (see heuristics in Step 0)
+   - Each of the 6 types should appear at least once if section count >= 6
+
+3. **Write theory text** per section:
+   - 150-400 words per section
+   - Structure: context -> core concept -> practical application
+   - Use newlines for paragraph separation
+   - Include **bold** for key terms
+   - Keep language consistent with source material
+
+4. **Assign icons** (emoji) per section:
+   - Relevant to the topic
+   - Distinct across sections (no duplicates)
+
+5. **Define section metadata:**
+   ```javascript
+   {
+     id: 'kebab-case-unique',  // 2-4 words, descriptive
+     order: 1,                  // Sequential from 1
+     title: 'N. Full Title',   // With order number prefix
+     shortTitle: 'Short Name', // For sidebar (2-3 words)
+     description: 'One-line summary of this section',
+     icon: 'emoji',
+     interactiveType: 'quiz' | 'flashcards' | 'matching' | 'drag-and-drop' | 'builder' | 'simulation' | 'scenario',
+     theory: 'Multi-paragraph theory text...'
+   }
+   ```
+
+6. **Define final test questions:**
+   - One question per section (for final assessment)
+   - 4 options each, one correct
+   - Test understanding, not memorization
+
+## Constraints
+
+- Minimum 3 sections, maximum 20
+- Each section must have exactly 1 exercise type
+- `interactiveType` must be one of the 6 supported types:
+  - `'quiz'` -> Quiz component
+  - `'flashcards'` -> Flashcard component
+  - `'matching'` -> MatchingExercise component
+  - `'drag-and-drop'` or `'ordering'` -> DragOrder component
+  - `'builder'` -> CommandBuilder component
+  - `'simulation'` or `'scenario'` -> ScenarioGame component
+
+## Output
+
+Section definitions ready for `sections.js` generation in Step 2.
+
+## Checkpoint
+
+```
+Step 1/7: Course Structure Complete
+Sections: N defined
+
+1. {icon} {title} — {interactiveType}
+2. ...
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/02-data-generation.md

@@ -0,0 +1,186 @@
+# Step 2: Data Generation
+
+## Goal
+Generate all data files (`sections.js`, `exercises.js`, `quizQuestions.js`, `achievements.js`) from the course structure.
+
+## Protocol
+
+Read `references/data-schemas.md` for exact data formats.
+
+### 1. Generate `src/data/sections.js`
+
+```javascript
+export const SECTIONS = [
+  {
+    id: 'section-id',
+    order: 1,
+    title: '1. Section Title',
+    shortTitle: 'Short Title',
+    description: 'Description',
+    icon: 'emoji',
+    interactiveType: 'type',
+    theory: `Theory text with **bold** and paragraphs separated by \\n\\n`
+  },
+  // ... one per section
+]
+
+export const TOTAL_SECTIONS = SECTIONS.length
+```
+
+### 2. Generate `src/data/exercises.js`
+
+For each section, generate exercise data matching its type:
+
+**Flashcards:**
+```javascript
+export const flashcardData = {
+  'section-id': [
+    { front: 'Term or question', back: 'Definition or answer' },
+    // 4-8 cards per section
+  ]
+}
+```
+
+**Matching:**
+```javascript
+export const matchingData = {
+  'section-id': [
+    { left: 'Item A', right: 'Match A' },
+    // 4-6 pairs per section
+  ]
+}
+```
+
+**Drag Order:**
+```javascript
+export const dragOrderData = {
+  'section-id': {
+    instruction: 'Arrange these in correct order:',
+    items: [{ id: '1', label: 'Step 1' }, ...],
+    correctOrder: ['1', '2', '3', ...]
+  }
+}
+// Also export as orderingData if section uses 'ordering' type
+```
+
+**Command Builder:**
+```javascript
+export const commandBuilderData = {
+  'section-id': {
+    instruction: 'Build the correct command:',
+    parts: ['part1', ' ', 'part2', ...],
+    correctCommand: 'part1 part2...',
+    hints: ['Hint for first part', 'Hint for second part']
+  }
+}
+```
+
+**Scenario/Simulation:**
+```javascript
+export const simulationData = {
+  'section-id': {
+    title: 'Scenario Title',
+    scenario: 'Context description',
+    steps: [
+      {
+        id: 'step1',
+        description: 'What do you do?',
+        options: [
+          { id: 'a', text: 'Good choice', result: 'positive', feedback: 'Why this is good' },
+          { id: 'b', text: 'OK choice', result: 'neutral', feedback: 'Why this is OK' },
+          { id: 'c', text: 'Bad choice', result: 'negative', feedback: 'Why this is bad' }
+        ]
+      },
+      // 3-5 steps per scenario
+    ]
+  }
+}
+// Also export as scenarioData for 'scenario' type sections
+```
+
+**FAQ:**
+```javascript
+export const faqData = [
+  { question: 'Frequently asked question?', answer: 'Detailed answer.' },
+  // 5-8 FAQ items about the course topic
+]
+```
+
+### 3. Generate `src/data/quizQuestions.js`
+
+**Per-section quizzes** (for sections with `interactiveType: 'quiz'`):
+```javascript
+export const quizQuestions = {
+  'section-id': [
+    {
+      id: 'section-id-q1',
+      question: 'Question text?',
+      options: ['Option A', 'Option B', 'Option C', 'Option D'],
+      correctAnswer: 0,  // index
+      explanation: 'Why this is correct'
+    },
+    // 2-4 questions per section
+  ]
+}
+```
+
+**Final test** (one question per section):
+```javascript
+export const finalTestQuestions = [
+  {
+    id: 'final-section-id',
+    sectionId: 'section-id',
+    question: 'Comprehensive question about this section?',
+    options: ['A', 'B', 'C', 'D'],
+    correctAnswer: 1
+  },
+  // one per section
+]
+```
+
+### 4. Generate `src/data/achievements.js`
+
+Standard achievement set (adapted to section count N):
+
+```javascript
+export const ACHIEVEMENTS = [
+  {
+    id: 'first-step',
+    title: 'First Step',           // Localized
+    description: 'Complete your first section',
+    icon: 'emoji',
+    condition: (state) => Object.keys(state.completedSections).length >= 1
+  },
+  // Halfway achievement (N/2 sections)
+  // Perfectionist (any section 100%)
+  // Full course (all N sections)
+  // Test passed (final test >= 70%)
+  // 3-5 topic-specific achievements
+]
+```
+
+**Achievement guidelines:**
+- Always include: first-step, halfway, perfectionist, full-course, test-passed
+- Add 3-5 topic-specific achievements based on related section groups
+- Total: 8-12 achievements
+- Icons should be distinct and relevant
+
+## Quality Checks
+
+- [ ] Every section in SECTIONS has matching exercise data
+- [ ] Every quiz section has questions in quizQuestions
+- [ ] finalTestQuestions has exactly one entry per section
+- [ ] All IDs are unique and kebab-case
+- [ ] correctAnswer indices are within options array bounds
+- [ ] No duplicate FAQ questions
+- [ ] Achievement conditions reference valid state properties
+
+## Checkpoint
+
+```
+Step 2/7: Data Generation Complete
+Files: sections.js, exercises.js, quizQuestions.js, achievements.js
+Sections: N | Quiz questions: M | Final test: N questions | Achievements: K
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/03-scaffold.md

@@ -0,0 +1,249 @@
+# Step 3: Project Scaffold
+
+## Goal
+Create the project skeleton: package.json, vite config, index.html, CSS theme, ESLint.
+
+## Protocol
+
+Read `references/tech-stack.md` for versions and configuration.
+
+### 1. Determine `base` path
+
+```javascript
+// Derive from git remote URL
+// git remote get-url origin → https://github.com/{user}/{repo}.git
+// base = '/{repo}/'
+```
+
+If no git remote, ask user for the GitHub repo name.
+
+### 2. Create `package.json`
+
+```json
+{
+  "name": "{repo-name}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.13.1",
+    "zustand": "^5.0.11",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2"
+  },
+  "devDependencies": {
+    "vite": "^7.3.1",
+    "@vitejs/plugin-react": "^5.1.1",
+    "tailwindcss": "^4.2.1",
+    "@tailwindcss/vite": "^4.2.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.1.0"
+  }
+}
+```
+
+### 3. Create `vite.config.js`
+
+```javascript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  base: '/{repo-name}/',
+  build: {
+    outDir: 'dist',
+  },
+})
+```
+
+### 4. Create `index.html`
+
+- `lang` attribute matches course language
+- Title = course title
+- SEO meta tags: description, keywords, author
+- Open Graph tags: title, description, type, url, image
+- Twitter Card meta
+- JSON-LD structured data (Course type)
+- Favicon (optional)
+- `<div id="root"></div>`
+- `<script type="module" src="/src/main.jsx"></script>`
+
+### 5. Create `public/robots.txt`
+
+```
+User-agent: *
+Allow: /
+Sitemap: https://{user}.github.io/{repo-name}/sitemap.xml
+```
+
+Replace `{user}` and `{repo-name}` with actual GitHub username and repository name.
+
+### 6. Create `public/sitemap.xml`
+
+Generate a sitemap listing all course sections:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://{user}.github.io/{repo-name}/</loc>
+    <lastmod>{build-date}</lastmod>
+    <priority>1.0</priority>
+  </url>
+  <!-- One <url> entry per section -->
+  <url>
+    <loc>https://{user}.github.io/{repo-name}/#section-{id}</loc>
+    <lastmod>{build-date}</lastmod>
+    <priority>0.8</priority>
+  </url>
+</urlset>
+```
+
+Use ISO 8601 date format for `{build-date}`. Generate one `<url>` entry for each section in the SECTIONS array.
+
+### 7. Create `src/index.css`
+
+TailwindCSS v4 configuration with semantic color tokens:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary-50: #eff6ff;
+  --color-primary-100: #dbeafe;
+  --color-primary-200: #bfdbfe;
+  --color-primary-300: #93c5fd;
+  --color-primary-400: #60a5fa;
+  --color-primary-500: #3b82f6;
+  --color-primary-600: #2563eb;
+  --color-primary-700: #1d4ed8;
+  --color-primary-800: #1e40af;
+  --color-primary-900: #1e3a8a;
+
+  --color-accent-400: #c084fc;
+  --color-accent-500: #a855f7;
+  --color-accent-600: #9333ea;
+
+  --color-success-400: #4ade80;
+  --color-success-500: #22c55e;
+  --color-success-600: #16a34a;
+  --color-success-700: #15803d;
+
+  --color-danger-400: #f87171;
+  --color-danger-500: #ef4444;
+  --color-danger-600: #dc2626;
+  --color-danger-700: #b91c1c;
+
+  --color-surface: var(--surface);
+  --color-card: var(--card);
+  --color-text: var(--text);
+  --color-text-secondary: var(--text-secondary);
+  --color-text-muted: var(--text-muted);
+  --color-border: var(--border);
+  --color-border-light: var(--border-light);
+  --color-bg-secondary: var(--bg-secondary);
+  --color-bg-hover: var(--bg-hover);
+}
+
+:root {
+  --surface: #f8fafc;
+  --card: #ffffff;
+  --text: #1e293b;
+  --text-secondary: #475569;
+  --text-muted: #94a3b8;
+  --border: #e2e8f0;
+  --border-light: #f1f5f9;
+  --bg-secondary: #f1f5f9;
+  --bg-hover: #f8fafc;
+}
+
+.dark {
+  --surface: #0f172a;
+  --card: #1e293b;
+  --text: #e2e8f0;
+  --text-secondary: #94a3b8;
+  --text-muted: #64748b;
+  --border: #334155;
+  --border-light: #1e293b;
+  --bg-secondary: #1e293b;
+  --bg-hover: #334155;
+}
+
+body {
+  @apply bg-surface text-text min-h-screen;
+}
+
+/* Custom animations */
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  20%, 60% { transform: translateX(-5px); }
+  40%, 80% { transform: translateX(5px); }
+}
+@keyframes bounce-in {
+  0% { transform: scale(0.3); opacity: 0; }
+  50% { transform: scale(1.05); }
+  70% { transform: scale(0.9); }
+  100% { transform: scale(1); opacity: 1; }
+}
+@keyframes fade-in-up {
+  from { opacity: 0; transform: translateY(10px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@utility animate-shake { animation: shake 0.5s ease-in-out; }
+@utility animate-bounce-in { animation: bounce-in 0.5s ease-out; }
+@utility animate-fade-in-up { animation: fade-in-up 0.3s ease-out; }
+```
+
+### 6. Create `eslint.config.js`
+
+Standard React + hooks ESLint config.
+
+### 7. Create `src/main.jsx`
+
+```jsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.jsx'
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)
+```
+
+### 8. Run `npm install`
+
+Install all dependencies.
+
+### 9. Create directory structure
+
+```
+mkdir -p src/{components/{layout,interactive,common,sections,final-test},data,store,hooks,pages}
+```
+
+## Checkpoint
+
+```
+Step 3/7: Project Scaffold Complete
+Base path: /{repo-name}/
+Dependencies installed: yes
+Files: package.json, vite.config.js, index.html, index.css, main.jsx, eslint.config.js
+
+"ok" to continue | "[feedback]" to adjust
+```