mnaimfaizy · mnaimfaizy · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
@@ -0,0 +1,79 @@
+---
+name: "Module Quiz Generator"
+description: "Use when generating, expanding, or updating module quiz banks in quiz-banks/{module}.quiz.json, especially for scenario-based questions, duplicate detection, and answer/reference deduplication."
+tools: [read, search, edit]
+user-invocable: true
+agents: []
+---
+
+You are a specialist at maintaining module quiz banks for Code Executives.
+
+## Scope
+- Your primary target is the root-level file `quiz-banks/{module}.quiz.json`.
+- You may read module content from `src/features/{module}/**` and shared metadata from `src/shared/constants/moduleNavigation.ts`.
+- You should not modify runtime code unless the parent task explicitly asks for schema changes.
+
+## Non-Negotiable Rules
+- Always read the entire existing quiz bank before proposing any update.
+- Never create a duplicate question.
+- Never create a duplicate answer set for a near-identical scenario.
+- Preserve existing ids for unchanged questions.
+- When appending new questions, continue the sequence with the next module-specific id, for example `javascript-q32` after `javascript-q31`.
+- Use only valid section labels that already exist for that module in `src/shared/constants/moduleNavigation.ts`.
+- Keep questions scenario-based and non-trivial.
+- Maintain the repository quiz-bank schema exactly.
+
+## Required Bank Schema
+Each bank must remain a single JSON object with:
+- `moduleId`
+- `moduleTitle`
+- `description`
+- `version`
+- `timeLimitMinutes`
+- `questionsPerAttempt`
+- `questions`
+
+Each question must include:
+- `id`
+- `type`
+- `difficulty`
+- `scenario`
+- `prompt`
+- `explanation`
+- `tags`
+- `references`
+
+Type-specific fields:
+- `single-choice` and `true-false`: `options`, `correctAnswer:number`
+- `multi-select`: `options`, `correctAnswer:number[]`
+- `ordering`: `items`, `correctAnswer:string[]`
+- `matching`: `premises`, `responses`, `correctAnswer:number[]`
+
+## Update Workflow
+1. Identify the module and read the module section files that define the learning content.
+2. Read `quiz-banks/{module}.quiz.json` in full if it exists.
+3. Build a normalized dedupe key for each existing question using:
+   - normalized `prompt`
+   - normalized `scenario`
+   - `type`
+   - normalized correct-answer payload
+   - normalized reference label set
+4. Generate only scenario-based questions that are meaningfully distinct from the existing bank.
+5. Reject any generated question that collides with an existing dedupe key or substantially repeats the same answer pattern for the same concept.
+6. Validate that every reference label exists for the module.
+7. Validate that the final JSON remains well-formed and schema-complete.
+
+## Quality Bar
+- Prefer advanced and expert questions over recall-only prompts.
+- Use operational, debugging, architecture, performance, or incident-response scenarios.
+- Include multiple question types where appropriate instead of only single-choice.
+- Explanations must explain why the best answer is correct, not just restate it.
+
+## Output Format
+Return a short summary with:
+- module name
+- file touched
+- questions added
+- questions updated
+- duplicates skipped
+- highest question id after the update
@@ -4,7 +4,7 @@
 
 **🌐 Live Website**: [https://codexecutives.com](https://codexecutives.com)
 
-**✨ Now featuring 14 complete learning modules with 90+ interactive visualizations covering Git, JavaScript Engine, RxJS, Data Structures, Next.js, Big-O Notation, Python Programming, AI Fundamentals, Node.js Ecosystem, DevOps & Cloud Computing, Auth & Security and a LeetCode-style playground with advanced debugging and gamification.**
+**✨ Now featuring 14 complete learning modules with 90+ interactive visualizations, root-level scenario quiz banks for every module, shared timed quizzes with local progress tracking, and a LeetCode-style playground with advanced debugging and gamification.**
 
 > **📌 Repository Maintainers**: See [REPOSITORY-ABOUT-QUICK-REFERENCE.md](./docs/REPOSITORY-ABOUT-QUICK-REFERENCE.md) for GitHub repository About section configuration (description, website, and topics).
 
@@ -23,6 +23,7 @@
 - **Node.js Ecosystem**: Deep dive into Event Loop, V8 memory, Streams, Clustering, module systems, package managers, frameworks, and runtime wars (Node vs Deno vs Bun)
 - **DevOps & Cloud Computing**: CI/CD pipelines, cloud service models (IaaS/PaaS/SaaS/FaaS), container orchestration with Kubernetes, Infrastructure as Code, observability, and modern DevOps roles
 - **Auth & Security**: Modern authentication and authorization — OAuth 2.0, OIDC, PKCE, WebAuthn/Passkeys, Zero Trust, BFF Pattern, and AI agent authentication
+- **Shared Timed Module Quizzes**: Every learning module ends with a 5-question, 10-minute scenario quiz backed by a root-level JSON bank and localStorage result history
 - **LeetCode-Style Playground**: Interactive coding environment with debugging, visualizations, and gamification
 
 ### 🎮 **Interactive Visualizations**
@@ -47,6 +48,16 @@
 - **Keyboard Shortcuts**: F10 (step), F5 (continue/pause), F11 (reset), Space (pause/resume)
 - **Rate-Limited Output**: Console entries capped at 500, oversized strings truncated to 50 KB
 
+### 🧠 **Timed Module Quizzes**
+
+- **Shared Quiz Runtime**: One reusable quiz system powers every learning module while preserving module-specific styling and references
+- **Root-Level Quiz Banks**: Each module has a dedicated JSON file in `quiz-banks/{module}.quiz.json`
+- **Scenario-Based Questions**: Every bank contains 30+ harder prompts with single-choice, multi-select, true/false, ordering, and matching formats
+- **10-Minute Timer**: Each run samples 5 questions and persists the active attempt across refreshes
+- **Local Progress History**: Scores, tiers, and recent attempts are stored in localStorage on the learner's machine
+- **Wrong-Answer References**: Review mode links learners back to the exact module sections that support the missed concept
+- **Authoring Workflow**: The workspace agent `.github/agents/module-quiz-generator.agent.md` maintains quiz banks without duplicating questions or answer sets
+
 ### 🎨 **Modern User Experience**
 
 - **Responsive Design**: Works seamlessly on desktop, tablet, and mobile
@@ -78,6 +89,7 @@
 ## 📁 Project Structure
 
 ```
+quiz-banks/              # Root-level module quiz banks named {module}.quiz.json
 src/
 ├── components/           # Reusable UI components
 │   ├── models2d/        # 2D visualization components
@@ -118,21 +130,49 @@ src/
 │   ├── bigo/           # Big-O notation concepts (8 sections)
 │   └── python/         # Python programming concepts (5 sections)
 ├── hooks/              # Custom React hooks
+├── shared/
+│   ├── components/
+│   │   └── quiz/       # Shared timed quiz UI and answer renderers
+│   ├── constants/
+│   │   └── moduleNavigation.ts # Shared module navigation and reference metadata
+│   └── hooks/
+│       └── useQuizSession.ts # Timed quiz session and localStorage persistence
 ├── types/              # TypeScript type definitions
 │   ├── nextjs.ts       # Next.js type definitions
 │   ├── datastructures.ts # Data structures type definitions
 │   ├── bigo.ts         # Big-O notation type definitions
 │   ├── python.ts       # Python programming type definitions
-│   └── playground.ts   # Playground type definitions
+│   ├── playground.ts   # Playground type definitions
+│   └── quiz.ts         # Shared quiz schema and result types
 ├── utils/              # Utility functions
 │   ├── instrument.ts   # Code instrumentation for debugging
 │   ├── memoryMonitor.ts # Performance monitoring
+│   ├── quiz.ts         # Quiz loading, scoring, and answer utilities
 │   └── theme.ts        # Theme and styling utilities
 ├── data/               # Static data and problem sets
 │   └── problems.ts     # LeetCode-style coding problems
 └── three/              # Three.js 3D models and scenes
 ```
 
+### Quiz Bank Naming
+
+- `quiz-banks/javascript.quiz.json`
+- `quiz-banks/rxjs.quiz.json`
+- `quiz-banks/git.quiz.json`
+- `quiz-banks/datastructures.quiz.json`
+- `quiz-banks/react.quiz.json`
+- `quiz-banks/nextjs.quiz.json`
+- `quiz-banks/bigo.quiz.json`
+- `quiz-banks/python.quiz.json`
+- `quiz-banks/systemdesign.quiz.json`
+- `quiz-banks/typescript.quiz.json`
+- `quiz-banks/ai.quiz.json`
+- `quiz-banks/nodejs.quiz.json`
+- `quiz-banks/devops.quiz.json`
+- `quiz-banks/auth.quiz.json`
+
+See `docs/Quiz-System-Guide.md` for the JSON schema, localStorage behavior, and the quiz-bank authoring workflow.
+
 ## 🚀 Quick Start
 
 ### Prerequisites

@@ -12,6 +12,7 @@ This document describes the layout and structure of the Code Executives web appl
 - **Sidebar**: Collapsible drawer, context-sensitive. Shows JavaScript theory sections only on the JavaScript page.
 - **Footer**: Simple footer with copyright and About link.
 - **Main Content**: Renders the current page based on the route.
+- **Timed Module Quiz Layer**: Shared end-of-module quiz section rendered inside every learning module, using query-param section routing and root-level quiz banks.
 
 ---
 
@@ -22,6 +23,7 @@ This document describes the layout and structure of the Code Executives web appl
   - `/` → Home
   - `/about` → About
   - `/javascript` → JavaScript page (with tabs and sidebar sections)
+- Learning modules keep their existing route paths and append the shared quiz through `?section=Quiz` instead of adding separate routes.
 
 ---
 
@@ -40,13 +42,26 @@ This document describes the layout and structure of the Code Executives web appl
   - `Header.tsx`: AppBar with navigation and sidebar toggle.
   - `Sidebar.tsx`: Drawer with context-sensitive section links.
   - `Footer.tsx`: Footer bar.
+- `/src/shared/components/quiz/`
+  - `ModuleQuizSection.tsx`: Shared quiz shell used across all learning modules.
+  - `QuestionRenderer.tsx`: Shared renderer for single-choice, multi-select, true/false, ordering, and matching questions.
 - `/src/pages/`
   - `Home.tsx`: Home page.
   - `About.tsx`: About page.
   - `JavaScriptPage.tsx`: Main JavaScript theory/demo page.
   - `JavaScript2D.tsx`, `JavaScript3D.tsx`: Visualization canvases.
 - `/src/sections/`
   - Individual theory sub-section components (Introduction, EngineRuntime, etc.)
+- `/src/shared/hooks/`
+  - `useQuizSession.ts`: Loads root-level quiz banks, persists active attempts, and stores local quiz results in localStorage.
+- `/src/shared/constants/`
+  - `moduleNavigation.ts`: Shared module section metadata used for quiz references and navigation.
+- `/src/types/quiz.ts`
+  - Shared quiz schema for bank files, active attempts, and result summaries.
+- `/quiz-banks/`
+  - Root-level JSON quiz banks named `{module}.quiz.json` so agents and humans can discover them quickly.
+- `/.github/agents/module-quiz-generator.agent.md`
+  - Workspace agent for growing or updating module quiz banks without duplicating questions or answer sets.
 
 ---
 
@@ -55,6 +70,20 @@ This document describes the layout and structure of the Code Executives web appl
 - Sidebar is hidden by default and toggled via the header button.
 - Sidebar sections are shown only for the JavaScript page.
 - Clicking a sidebar section updates the query param and displays the corresponding theory component.
+- The quiz section is appended as the final sidebar entry for every learning module.
+- Wrong-answer review links resolve through the shared module navigation metadata so quiz references land on the correct module section.
+
+---
+
+## Quiz System
+
+- Every learning module now ends with a shared quiz experience.
+- Each quiz run samples 5 questions from a 30+ question module bank.
+- The timer is fixed at 10 minutes and survives refresh via localStorage.
+- Results are stored locally and exposed back to the learner in the module quiz sidebar.
+- Wrong answers link back to the relevant in-module sections for review.
+- Quiz content lives outside `src/` in the root-level `quiz-banks/` directory to keep authoring and agent discovery simple.
+- The `module-quiz-generator` custom agent is the canonical workflow for expanding or refreshing module quiz banks.
 
 ---
 
@@ -69,8 +98,8 @@ This document describes the layout and structure of the Code Executives web appl
 
 - Add more languages and context-sensitive sidebar sections.
 - Implement code editor and interactive demos for each mode.
-- Expand documentation as new features are added.
+- Expand the quiz-bank authoring guide as the generator workflow evolves.
 
 ---
 
-_Last updated: September 15, 2025_
+_Last updated: April 9, 2026_
@@ -0,0 +1,142 @@
+# Quiz System Guide
+
+## Overview
+
+Code Executives now includes a shared timed quiz system for every learning module except the Playground.
+
+- Each attempt uses 5 questions.
+- Each attempt has a 10-minute timer.
+- Every module bank contains 30+ scenario-based questions.
+- Attempts and results are stored in localStorage so the learner can resume an in-progress quiz after a refresh.
+- Wrong answers include deep links back into the relevant module sections.
+
+## Bank Location
+
+Quiz banks live at the repository root in `quiz-banks/`.
+
+Naming convention:
+
+- `quiz-banks/javascript.quiz.json`
+- `quiz-banks/rxjs.quiz.json`
+- `quiz-banks/git.quiz.json`
+- `quiz-banks/datastructures.quiz.json`
+- `quiz-banks/react.quiz.json`
+- `quiz-banks/nextjs.quiz.json`
+- `quiz-banks/bigo.quiz.json`
+- `quiz-banks/python.quiz.json`
+- `quiz-banks/systemdesign.quiz.json`
+- `quiz-banks/typescript.quiz.json`
+- `quiz-banks/ai.quiz.json`
+- `quiz-banks/nodejs.quiz.json`
+- `quiz-banks/devops.quiz.json`
+- `quiz-banks/auth.quiz.json`
+
+## JSON Schema
+
+Every bank is a single JSON object:
+
+```json
+{
+  "moduleId": "javascript",
+  "moduleTitle": "JavaScript",
+  "description": "Scenario-based assessment...",
+  "version": 1,
+  "timeLimitMinutes": 10,
+  "questionsPerAttempt": 5,
+  "questions": []
+}
+```
+
+Each question must include:
+
+- `id`
+- `type`
+- `difficulty`
+- `scenario`
+- `prompt`
+- `explanation`
+- `tags`
+- `references`
+
+Supported question types:
+
+- `single-choice`
+- `multi-select`
+- `true-false`
+- `ordering`
+- `matching`
+
+Type-specific fields:
+
+- `single-choice` and `true-false`: `options`, `correctAnswer:number`
+- `multi-select`: `options`, `correctAnswer:number[]`
+- `ordering`: `items`, `correctAnswer:string[]`
+- `matching`: `premises`, `responses`, `correctAnswer:number[]`
+
+## Runtime Files
+
+- `src/shared/components/quiz/ModuleQuizSection.tsx`
+- `src/shared/components/quiz/QuestionRenderer.tsx`
+- `src/shared/hooks/useQuizSession.ts`
+- `src/shared/constants/moduleNavigation.ts`
+- `src/types/quiz.ts`
+- `src/utils/quiz.ts`
+
+## localStorage Behavior
+
+Per-module storage keys use the prefix `code-executives.quiz`.
+
+For each module:
+
+- `code-executives.quiz.{module}.active-attempt`
+- `code-executives.quiz.{module}.results`
+
+The active-attempt key stores:
+
+- selected question ids
+- current answers
+- current question index
+- start timestamp
+- expiry timestamp
+
+The results key stores recent local summaries so learners can see prior scores and tiers.
+
+## Wrong-Answer References
+
+Question `references` use exact section labels from `src/shared/constants/moduleNavigation.ts`.
+
+At review time the runtime resolves those labels into module section links so learners can jump directly back into the source material.
+
+## Generator Agent
+
+Use the workspace custom agent:
+
+- `.github/agents/module-quiz-generator.agent.md`
+
+Its responsibilities:
+
+- read the full existing module bank first
+- inspect the module source content
+- generate only scenario-based, non-trivial questions
+- avoid duplicate questions and duplicate answer sets for near-identical prompts
+- preserve stable ids for unchanged questions
+- append new question ids sequentially
+
+## Authoring Rules
+
+- Keep question prompts scenario-based.
+- Prefer advanced and expert prompts over recall-only trivia.
+- Use exact section labels already defined for the module.
+- Keep explanations diagnostic and instructional.
+- Do not move quiz banks into `src/` or `public/`; the root-level `quiz-banks/` directory is canonical.
+
+## Validation Checklist
+
+Before merging quiz-bank changes:
+
+1. Confirm the JSON file remains valid.
+2. Confirm `moduleId` matches the filename.
+3. Confirm there are 30+ questions.
+4. Confirm at least 5 questions can be sampled without duplicate ids.
+5. Confirm reference labels exist in `src/shared/constants/moduleNavigation.ts`.
+6. Run `npm run build` to confirm the loader still compiles.