Adding handoff functionality for reviews

2026-03-13 11:10:32 +01:00
parent fdd275ac0e
commit 3dcd7961c6
35 changed files with 7181 additions and 326 deletions
@@ -0,0 +1,4 @@
+
+
+API_URL="${GNOMMO_API_URL:-https://glitch.university}" 
+CONTENT_API_KEY=782y497821y491y3981212 
@@ -0,0 +1,110 @@
+# Gnommo Content Skills
+
+Skills for generating content for the Gnommo/Glitch.University learning platform.
+
+## Available Skills
+
+| Skill | File | Purpose |
+|-------|------|---------|
+| DEGLITCH Gates | `deglitch-gate-generator.md` | Generate quiz questions from manuscripts |
+| Slide Content | `slide-content-generator.md` | Generate image prompts & text for slides |
+
+---
+
+# DEGLITCH Gate Generator
+
+Generate quiz questions from manuscript content for the Gnommo learning platform.
+
+## Quick Start
+
+1. Read `manuscript.txt` (or specified file)
+2. Identify 3-7 key concepts
+3. Create 1-2 questions per concept
+4. Output JSON or submit via API
+
+## Project Structure
+
+Each video project has:
+- `manuscript.txt` - The narration script with `[SX]` slide markers
+- `project.json` - Contains `coursecode` to identify the tech on the server
+
+## API Configuration
+
+```
+Base URL: ${GNOMMO_API_URL:-http://localhost:3001}
+Auth: Authorization: Bearer ${CONTENT_API_KEY}
+```
+
+## Endpoints
+
+- `GET /api/content/techs/available` - Find tech_id to link
+- `POST /api/content/deglitch-gates` - Create gate
+- `GET /api/content/deglitch-gates` - List gates
+- `PUT /api/content/deglitch-gates/:id` - Update gate
+
+## Question JSON Structure
+
+```json
+{
+  "tech_id": null,
+  "title": "Gate Title",
+  "description": "What this tests",
+  "passing_score": 0.8,
+  "shuffle_questions": true,
+  "shuffle_options": true,
+  "questions": [
+    {
+      "question_type": "radio",
+      "text": "Question?",
+      "sort_order": 0,
+      "options": {
+        "a": { "answer": "Wrong", "correct": false, "why": "Explanation" },
+        "b": { "answer": "Right", "correct": true, "why": "Explanation" },
+        "c": { "answer": "Wrong", "correct": false, "why": "Explanation" },
+        "d": { "answer": "Wrong", "correct": false, "why": "Explanation" }
+      }
+    }
+  ]
+}
+```
+
+## Question Types
+- `radio` - Single answer (most common)
+- `checkbox` - Multiple answers
+- `llm` - Free text (AI evaluated)
+
+## Quality Guidelines
+
+- Test understanding, not memorization
+- One clear correct answer per radio question
+- Plausible wrong answers with educational "why"
+- Concise questions, avoid trick questions
+- Vary difficulty across questions
+
+## Workflow with API Key
+
+```bash
+# 1. Read project.json to get coursecode
+cat /path/to/video/project.json | jq '.coursecode'
+
+# 2. Find tech_id by matching coursecode
+curl -H "Authorization: Bearer $CONTENT_API_KEY" \
+  $GNOMMO_API_URL/api/content/techs
+
+# 3. Create gate with matched tech_id
+curl -X POST -H "Authorization: Bearer $CONTENT_API_KEY" \
+  -H "Content-Type: application/json" \
+  $GNOMMO_API_URL/api/content/deglitch-gates \
+  -d '{"tech_id": 1, "title":"...","questions":[...]}'
+```
+
+## Matching Coursecode to Tech
+
+The `coursecode` in `project.json` matches the `code` field in the server's tech list:
+- `♟️_#1.0` → Lightlane series, Video 1
+- `♟️_#2.0` → Lightlane series, Video 2
+- `WTF_#1` → What is Glitch University series, Video 1
+
+## Workflow without API Key
+
+Output the complete JSON for manual entry or later API submission.
@@ -0,0 +1,141 @@
+#!/bin/bash
+# glitch gate API Helper Script
+# Usage: source this file, then use the functions
+
+# Configuration - set these or export before sourcing
+GNOMMO_API_URL="${GNOMMO_API_URL:-http://localhost:3001}"
+# CONTENT_API_KEY should be set in environment
+
+# Check if API key is set
+check_api_key() {
+  if [ -z "$CONTENT_API_KEY" ]; then
+    echo "Error: CONTENT_API_KEY not set"
+    echo "Run: export CONTENT_API_KEY=your-key-here"
+    return 1
+  fi
+}
+
+# List all techs
+list_techs() {
+  check_api_key || return 1
+  curl -s -H "Authorization: Bearer $CONTENT_API_KEY" \
+    "$GNOMMO_API_URL/api/content/techs" | jq
+}
+
+# List techs without gates (available for linking)
+list_available_techs() {
+  check_api_key || return 1
+  curl -s -H "Authorization: Bearer $CONTENT_API_KEY" \
+    "$GNOMMO_API_URL/api/content/techs/available" | jq
+}
+
+# List all glitch gates
+list_gates() {
+  check_api_key || return 1
+  curl -s -H "Authorization: Bearer $CONTENT_API_KEY" \
+    "$GNOMMO_API_URL/api/content/deglitch-gates" | jq
+}
+
+# Get a specific gate by ID
+get_gate() {
+  check_api_key || return 1
+  local gate_id=$1
+  if [ -z "$gate_id" ]; then
+    echo "Usage: get_gate <gate_id>"
+    return 1
+  fi
+  curl -s -H "Authorization: Bearer $CONTENT_API_KEY" \
+    "$GNOMMO_API_URL/api/content/deglitch-gates/$gate_id" | jq
+}
+
+# Create a gate from JSON file
+create_gate() {
+  check_api_key || return 1
+  local json_file=$1
+  if [ -z "$json_file" ]; then
+    echo "Usage: create_gate <json_file>"
+    return 1
+  fi
+  if [ ! -f "$json_file" ]; then
+    echo "Error: File not found: $json_file"
+    return 1
+  fi
+  curl -s -X POST \
+    -H "Authorization: Bearer $CONTENT_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @"$json_file" \
+    "$GNOMMO_API_URL/api/content/deglitch-gates" | jq
+}
+
+# Create a gate from JSON string
+create_gate_json() {
+  check_api_key || return 1
+  local json_data=$1
+  if [ -z "$json_data" ]; then
+    echo "Usage: create_gate_json '<json_string>'"
+    return 1
+  fi
+  curl -s -X POST \
+    -H "Authorization: Bearer $CONTENT_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$json_data" \
+    "$GNOMMO_API_URL/api/content/deglitch-gates" | jq
+}
+
+# Update a gate from JSON file
+update_gate() {
+  check_api_key || return 1
+  local gate_id=$1
+  local json_file=$2
+  if [ -z "$gate_id" ] || [ -z "$json_file" ]; then
+    echo "Usage: update_gate <gate_id> <json_file>"
+    return 1
+  fi
+  if [ ! -f "$json_file" ]; then
+    echo "Error: File not found: $json_file"
+    return 1
+  fi
+  curl -s -X PUT \
+    -H "Authorization: Bearer $CONTENT_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @"$json_file" \
+    "$GNOMMO_API_URL/api/content/deglitch-gates/$gate_id" | jq
+}
+
+# Delete a gate
+delete_gate() {
+  check_api_key || return 1
+  local gate_id=$1
+  if [ -z "$gate_id" ]; then
+    echo "Usage: delete_gate <gate_id>"
+    return 1
+  fi
+  read -p "Delete gate $gate_id? (y/N) " confirm
+  if [ "$confirm" = "y" ] || [ "$confirm" = "Y" ]; then
+    curl -s -X DELETE \
+      -H "Authorization: Bearer $CONTENT_API_KEY" \
+      "$GNOMMO_API_URL/api/content/deglitch-gates/$gate_id" | jq
+  else
+    echo "Cancelled"
+  fi
+}
+
+# Print available commands
+deglitch_help() {
+  echo "glitch gate API Commands:"
+  echo ""
+  echo "  list_techs           - List all techs"
+  echo "  list_available_techs - List techs without gates"
+  echo "  list_gates           - List all glitch gates"
+  echo "  get_gate <id>        - Get gate details"
+  echo "  create_gate <file>   - Create gate from JSON file"
+  echo "  create_gate_json '<json>' - Create gate from JSON string"
+  echo "  update_gate <id> <file>   - Update gate from JSON file"
+  echo "  delete_gate <id>     - Delete a gate"
+  echo ""
+  echo "Configuration:"
+  echo "  GNOMMO_API_URL=$GNOMMO_API_URL"
+  echo "  CONTENT_API_KEY=$([ -n "$CONTENT_API_KEY" ] && echo "[set]" || echo "[not set]")"
+}
+
+echo "DEGLITCH API helper loaded. Run 'deglitch_help' for commands."
@@ -0,0 +1,251 @@
+# glitch gate Generator Skill
+
+You are a quiz/assessment generator for the Gnommo learning platform. Your job is to read educational manuscript content and create glitch gate questions that test understanding.
+
+## What is a glitch gate?
+
+A glitch gate is a quiz that learners must pass to demonstrate mastery of a tech (lesson). Gates have:
+- A title and description
+- A passing score (default 80%)
+- Multiple questions with explanations for why each answer is correct/incorrect
+
+## Question Philosophy
+
+Create questions that test **understanding**, not memorization:
+
+- **Intuition questions**: Test pattern recognition and conceptual understanding
+- **Grit questions**: Present tricky scenarios requiring careful thinking
+- **Craft questions**: Test precise technical knowledge and attention to detail
+
+### Good Question Characteristics
+- Tests a single concept clearly
+- Has one unambiguously correct answer
+- Wrong answers are plausible (not obviously wrong)
+- Each answer has a "why" explanation
+- Avoids trick questions or gotchas
+
+## Workflow
+
+### Step 1: Read the Manuscript
+
+First, read the manuscript file to understand the content:
+
+```
+Read the file: manuscript.txt
+```
+
+Or if given a specific path:
+```
+Read the file: /path/to/manuscript.txt
+```
+
+### Step 2: Identify Key Concepts
+
+After reading, identify 3-7 key concepts that learners should understand. Consider:
+- Core principles explained in the text
+- Common misconceptions to address
+- Practical applications mentioned
+- Relationships between concepts
+
+### Step 3: Generate Questions
+
+For each key concept, create 1-2 questions. Use this JSON structure:
+
+```json
+{
+  "tech_id": null,
+  "title": "Gate Title Based on Content",
+  "description": "Brief description of what this gate tests",
+  "passing_score": 0.8,
+  "shuffle_questions": true,
+  "shuffle_options": true,
+  "is_active": true,
+  "questions": [
+    {
+      "question_type": "radio",
+      "text": "Question text here?",
+      "sort_order": 0,
+      "options": {
+        "a": {
+          "answer": "First option",
+          "correct": false,
+          "why": "Explanation of why this is incorrect"
+        },
+        "b": {
+          "answer": "Second option (correct)",
+          "correct": true,
+          "why": "Explanation of why this is correct"
+        },
+        "c": {
+          "answer": "Third option",
+          "correct": false,
+          "why": "Explanation of why this is incorrect"
+        },
+        "d": {
+          "answer": "Fourth option",
+          "correct": false,
+          "why": "Explanation of why this is incorrect"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Question Types
+
+- `radio` - Single correct answer (most common)
+- `checkbox` - Multiple correct answers
+- `llm` - Free text evaluated by AI (use sparingly)
+
+## Step 4: Submit to API (if API key available)
+
+If you have the Content API key, you can directly create the gate:
+
+```bash
+curl -X POST https://your-domain.com/api/content/deglitch-gates \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d 'YOUR_JSON_HERE'
+```
+
+### API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/content/techs` | List all techs to find tech_id |
+| GET | `/api/content/techs/available` | Techs without gates |
+| GET | `/api/content/deglitch-gates` | List existing gates |
+| POST | `/api/content/deglitch-gates` | Create new gate |
+| PUT | `/api/content/deglitch-gates/:id` | Update gate |
+| DELETE | `/api/content/deglitch-gates/:id` | Delete gate |
+
+### Finding the Right Tech ID
+
+Before creating a gate, list available techs to find the correct `tech_id`:
+
+```bash
+curl -X GET https://your-domain.com/api/content/techs/available \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+## Example: Complete Question Set
+
+Here's an example of a well-structured gate for an "Atomic Structure" lesson:
+
+```json
+{
+  "tech_id": 1,
+  "title": "Atomic Structure Fundamentals",
+  "description": "Test your understanding of basic atomic structure and the components of atoms.",
+  "passing_score": 0.8,
+  "shuffle_questions": true,
+  "shuffle_options": true,
+  "is_active": true,
+  "questions": [
+    {
+      "question_type": "radio",
+      "text": "What determines the chemical properties of an atom?",
+      "sort_order": 0,
+      "options": {
+        "a": {
+          "answer": "The number of neutrons",
+          "correct": false,
+          "why": "Neutrons affect atomic mass and stability, but not chemical properties directly."
+        },
+        "b": {
+          "answer": "The number of protons",
+          "correct": false,
+          "why": "Protons determine the element, but electrons determine how it bonds."
+        },
+        "c": {
+          "answer": "The number of electrons in the outer shell",
+          "correct": true,
+          "why": "Valence electrons determine how an atom bonds with others, defining its chemical behavior."
+        },
+        "d": {
+          "answer": "The total atomic mass",
+          "correct": false,
+          "why": "Atomic mass affects physical properties like density, not chemical reactivity."
+        }
+      }
+    },
+    {
+      "question_type": "radio",
+      "text": "An atom has 6 protons and 8 neutrons. What element is it?",
+      "sort_order": 1,
+      "options": {
+        "a": {
+          "answer": "Oxygen",
+          "correct": false,
+          "why": "Oxygen has 8 protons. The number of protons defines the element."
+        },
+        "b": {
+          "answer": "Carbon",
+          "correct": true,
+          "why": "Carbon has 6 protons. This is carbon-14, an isotope with 8 neutrons."
+        },
+        "c": {
+          "answer": "Nitrogen",
+          "correct": false,
+          "why": "Nitrogen has 7 protons."
+        },
+        "d": {
+          "answer": "Carbon-14 is not carbon",
+          "correct": false,
+          "why": "Isotopes are variants of the same element. Carbon-14 is still carbon."
+        }
+      }
+    },
+    {
+      "question_type": "radio",
+      "text": "Why are noble gases chemically inert?",
+      "sort_order": 2,
+      "options": {
+        "a": {
+          "answer": "They have no electrons",
+          "correct": false,
+          "why": "Noble gases have electrons; helium has 2, neon has 10, etc."
+        },
+        "b": {
+          "answer": "Their outer electron shell is full",
+          "correct": true,
+          "why": "A full valence shell means no tendency to gain, lose, or share electrons."
+        },
+        "c": {
+          "answer": "They are too heavy to react",
+          "correct": false,
+          "why": "Mass doesn't determine reactivity. Francium is heavy but highly reactive."
+        },
+        "d": {
+          "answer": "They only exist at very low temperatures",
+          "correct": false,
+          "why": "Noble gases exist at all temperatures; they're gases at room temperature."
+        }
+      }
+    }
+  ]
+}
+```
+
+## Tips for Quality Questions
+
+1. **Start with the concept**, then craft the question around it
+2. **Make wrong answers educational** - the "why" should teach something
+3. **Vary difficulty** - include some easier and some harder questions
+4. **Avoid "all of the above"** or "none of the above" options
+5. **Keep questions concise** - if it needs a lot of context, split it
+6. **Test understanding, not recall** - ask "why" and "how", not just "what"
+
+## Environment Variables
+
+If using the API programmatically, you need:
+- `CONTENT_API_KEY` - Your API key for authentication
+- API base URL (e.g., `https://gnommo.com` or `http://localhost:3001`)
+
+## Output Format
+
+When generating questions without API access, output:
+1. A summary of key concepts identified
+2. The complete JSON structure ready to copy
+3. Any notes about the questions or suggestions for the tech linking
@@ -0,0 +1,165 @@
+# Slide Content Generator Skill
+
+Generate slide content (image prompts or text) from Gnommo manuscript files.
+
+## Context
+
+Gnommo presentations use a **square slide area next to a talking head**. Slides should be:
+- Visually impactful but not cluttered
+- Timed to appear with the first word after the `[SX]` marker
+- Either **image-based** (generated via AI) or **text-based** (minimal, punchy text)
+
+## Manuscript Format
+
+Manuscripts use slide markers like `[S1]`, `[S2]`, etc. The content following each marker is what the presenter says while that slide is displayed.
+
+```
+[S1]
+Welcome to the course...
+
+[S2]
+What if the universe is discrete?
+```
+
+## Workflow
+
+### Step 1: Read the Manuscript
+
+```
+Read the file: /path/to/manuscript.txt
+```
+
+### Step 2: Analyze Each Slide
+
+For each `[SX]` marker, determine:
+1. **What is the core message?** - The key idea being communicated
+2. **Visual or text?** - Would an image or text better support the message?
+3. **Emotional tone?** - Dramatic, contemplative, humorous, technical?
+
+### Step 3: Generate Content
+
+For each slide, output one of:
+
+#### IMAGE PROMPT
+For conceptual, emotional, or complex ideas that benefit from visualization.
+
+```
+**[SX]** - "First few words..."
+**IMAGE PROMPT:**
+`Detailed description for AI image generation, style, mood, composition, lighting, specific elements to include`
+```
+
+#### TEXT SLIDE
+For lists, key terms, definitions, or when words ARE the point.
+
+```
+**[SX]** - "First few words..."
+**TEXT SLIDE:**
+```
+HEADLINE
+
+• Bullet point
+• Another point
+```
+```
+
+## Guidelines
+
+### When to Use IMAGE PROMPTS
+
+- Abstract concepts (e.g., "the fabric of spacetime")
+- Metaphors and analogies (e.g., "like changing engines while driving")
+- Emotional moments (e.g., "this sounds insane")
+- Scene-setting (e.g., "imagine a Minecraft universe")
+
+### When to Use TEXT SLIDES
+
+- Lists of items being enumerated
+- Technical terms being defined
+- Key questions or frameworks
+- Course titles, section headers
+- Quotes or key phrases
+
+### Image Prompt Best Practices
+
+1. **Be specific about style**: "isometric illustration", "cinematic lighting", "minimal vector style"
+2. **Include mood/tone**: "mysterious", "hopeful", "dramatic contrast"
+3. **Describe composition**: "split image", "centered subject", "deep space background"
+4. **Avoid text in images**: AI image generators struggle with text - use text slides instead
+5. **Keep it achievable**: Don't describe impossibly complex scenes
+
+### Text Slide Best Practices
+
+1. **Minimal words**: 3-7 words per line, 1-5 lines max
+2. **Use hierarchy**: HEADLINES in caps, details below
+3. **Bullets for lists**: Keep them short and scannable
+4. **Leave breathing room**: Don't fill the entire square
+
+## Output Format
+
+Output slides in order, with clear separation:
+
+```markdown
+---
+
+**[S1]** - "First words of narration..."
+**TYPE:** (IMAGE PROMPT or TEXT SLIDE)
+Content here
+
+---
+
+**[S2]** - "First words of narration..."
+...
+```
+
+## Example Output
+
+---
+
+**[S1]** - "Welcome to Glitch.University..."
+**TEXT SLIDE:**
+```
+GLITCH.UNIVERSITY
+WTF_#1
+
+What is Glitch University?
+```
+
+---
+
+**[S2]** - "What if the universe is fundamentally discrete..."
+**IMAGE PROMPT:**
+`A hyper-detailed Minecraft-style voxel universe, showing galaxies and stars rendered as tiny glowing cubes, deep space background with blocky nebulae, cosmic scale but pixelated, dark background with vibrant cube-shaped stars, cinematic lighting`
+
+---
+
+## Customization Options
+
+### Style Presets
+
+You can request specific visual styles:
+- **Tech/Corporate**: Clean vectors, isometric, blues and whites
+- **Cosmic/Physics**: Deep space, nebulae, particle effects
+- **Playful/Minecraft**: Voxels, bright colors, blocky
+- **Philosophical**: Abstract, minimal, contemplative
+- **Dramatic**: High contrast, cinematic, intense lighting
+
+### Text Tone
+
+- **Academic**: Formal terminology, structured
+- **Casual**: Conversational, approachable
+- **Punchy**: Short, impactful, memorable
+
+## Integration with Gnommo
+
+The generated content can be used to:
+1. Create slides in Keynote/PowerPoint
+2. Generate images via Midjourney/DALL-E/Stable Diffusion
+3. Populate the `slides.json` file in the project's media folder
+
+## Tips
+
+- Read the ENTIRE manuscript first to understand the arc
+- Match slide density to pacing - fast sections need simpler slides
+- Create visual continuity - recurring metaphors should have consistent imagery
+- Consider what the talking head is doing - slides complement, not compete