From e48e6ebda37ac782c453d4309b55f7114ae76019 Mon Sep 17 00:00:00 2001
From: CarterPerez-dev <cartertechsolution@gmail.com>
Date: Sat, 31 Jan 2026 01:05:28 -0500
Subject: [PATCH] Phase 3.1: Create learn/ folder template

- Add comprehensive 5-file template structure
- 00-OVERVIEW.md: Project intro, quick start, prerequisites
- 01-CONCEPTS.md: Security concepts with real world examples
- 02-ARCHITECTURE.md: System design and technical decisions
- 03-IMPLEMENTATION.md: Code walkthrough with actual examples
- 04-CHALLENGES.md: Extension ideas from easy to expert
- README.md: Template usage guide and writing guidelines
- CHECKLIST.md: Quick reference for filling templates

Writing guidelines emphasize:
- Human voice (avoiding AI patterns like em dashes, contrast flips)
- Concrete examples over abstractions
- Real code references with file:line numbers
- Real world incidents and vulnerabilities
- Practical, actionable content
---
 .github/learn-folder-template/00-OVERVIEW.md  | 101 ++++
 .github/learn-folder-template/01-CONCEPTS.md  | 139 +++++
 .../learn-folder-template/02-ARCHITECTURE.md  | 370 ++++++++++++
 .../03-IMPLEMENTATION.md                      | 545 ++++++++++++++++++
 .../learn-folder-template/04-CHALLENGES.md    | 420 ++++++++++++++
 .github/learn-folder-template/CHECKLIST.md    | 116 ++++
 .github/learn-folder-template/README.md       | 264 +++++++++
 7 files changed, 1955 insertions(+)
 create mode 100644 .github/learn-folder-template/00-OVERVIEW.md
 create mode 100644 .github/learn-folder-template/01-CONCEPTS.md
 create mode 100644 .github/learn-folder-template/02-ARCHITECTURE.md
 create mode 100644 .github/learn-folder-template/03-IMPLEMENTATION.md
 create mode 100644 .github/learn-folder-template/04-CHALLENGES.md
 create mode 100644 .github/learn-folder-template/CHECKLIST.md
 create mode 100644 .github/learn-folder-template/README.md

diff --git a/.github/learn-folder-template/00-OVERVIEW.md b/.github/learn-folder-template/00-OVERVIEW.md
new file mode 100644
index 00000000..4ad0721a
--- /dev/null
+++ b/.github/learn-folder-template/00-OVERVIEW.md
@@ -0,0 +1,101 @@
+# [Project Name]
+
+## What This Is
+
+[2-3 sentence description of what the project does. Be specific about functionality, not buzzwords.]
+
+## Why This Matters
+
+[Explain the real world problem this solves. Reference actual incidents, common vulnerabilities, or industry pain points. No fluff about "the evolving threat landscape" - get concrete.]
+
+**Real world scenarios where this applies:**
+- [Specific scenario 1]
+- [Specific scenario 2]
+- [Specific scenario 3]
+
+## What You'll Learn
+
+This project teaches you how [core concept] works under the hood. By building it yourself, you'll understand:
+
+**Security Concepts:**
+- [Concept 1 - explain what it is, not just list it]
+- [Concept 2]
+- [Concept 3]
+
+**Technical Skills:**
+- [Skill 1 - be specific about what aspect you'll actually implement]
+- [Skill 2]
+- [Skill 3]
+
+**Tools and Techniques:**
+- [Tool/technique 1 - explain how it's used in the project]
+- [Tool/technique 2]
+
+## Prerequisites
+
+Before starting, you should understand:
+
+**Required knowledge:**
+- [Prerequisite 1 with specific examples of what you need to know]
+- [Prerequisite 2]
+- [Prerequisite 3]
+
+**Tools you'll need:**
+- [Tool 1] - [brief explanation of why]
+- [Tool 2]
+- [Tool 3]
+
+**Helpful but not required:**
+- [Nice to have 1]
+- [Nice to have 2]
+
+## Quick Start
+
+Get the project running locally:
+
+```bash
+# Clone and navigate
+cd PROJECTS/[difficulty]/[project-name]
+
+# [Installation steps specific to the project]
+# Keep this minimal - just enough to see it work
+
+# Run the project
+[command to start]
+```
+
+Expected output: [describe what success looks like]
+
+## Project Structure
+
+```
+[project-name]/
+├── [key directory 1]/    # [what this contains]
+├── [key directory 2]/    # [what this contains]
+├── [key file 1]          # [what this does]
+└── [key file 2]          # [what this does]
+```
+
+## Next Steps
+
+1. **Understand the concepts** - Read [01-CONCEPTS.md](./01-CONCEPTS.md) to learn the security fundamentals
+2. **Study the architecture** - Read [02-ARCHITECTURE.md](./02-ARCHITECTURE.md) to see how it's designed
+3. **Walk through the code** - Read [03-IMPLEMENTATION.md](./03-IMPLEMENTATION.md) for implementation details
+4. **Extend the project** - Read [04-CHALLENGES.md](./04-CHALLENGES.md) for ideas to build on
+
+## Common Issues
+
+**[Common problem 1]**
+```
+[Error message or symptom]
+```
+Solution: [How to fix it]
+
+**[Common problem 2]**
+Solution: [How to fix it]
+
+## Related Projects
+
+If you found this interesting, check out:
+- [Related project 1] - [why it's related]
+- [Related project 2] - [why it's related]
diff --git a/.github/learn-folder-template/01-CONCEPTS.md b/.github/learn-folder-template/01-CONCEPTS.md
new file mode 100644
index 00000000..4283682d
--- /dev/null
+++ b/.github/learn-folder-template/01-CONCEPTS.md
@@ -0,0 +1,139 @@
+# Core Security Concepts
+
+This document explains the security concepts you'll encounter while building this project. These are not just definitions - we'll dig into why they matter and how they actually work.
+
+## [Primary Concept]
+
+### What It Is
+
+[Explain the concept in plain language. No jargon without explanation. Assume the reader is smart but unfamiliar.]
+
+### Why It Matters
+
+[Explain the real world impact. What goes wrong without it? Reference actual breaches or incidents if relevant.]
+
+### How It Works
+
+[Break down the technical mechanism. Use examples and code snippets where helpful. ASCII diagrams are good.]
+
+```
+[Diagram or code example showing the concept in action]
+```
+
+### Common Attacks
+
+[List specific attack techniques that exploit this. Be concrete about what an attacker does.]
+
+1. **[Attack 1]** - [How it works, what the attacker gains]
+2. **[Attack 2]** - [How it works, what the attacker gains]
+3. **[Attack 3]** - [How it works, what the attacker gains]
+
+### Defense Strategies
+
+[Explain how to protect against these attacks. Connect back to what this project implements.]
+
+## [Secondary Concept]
+
+### What It Is
+
+[Same structure as above]
+
+### Why It Matters
+
+[Real world impact]
+
+### How It Works
+
+[Technical mechanism]
+
+### Common Pitfalls
+
+[Where developers get this wrong. Based on actual mistakes you see in production code.]
+
+**Mistake 1: [Common error]**
+```[language]
+# Bad
+[code showing the mistake]
+
+# Good
+[code showing the correct approach]
+```
+
+**Mistake 2: [Another common error]**
+[Explanation of why this is wrong]
+
+## [Additional Concept]
+
+[Follow same pattern for each major concept]
+
+## How These Concepts Relate
+
+[Show how the concepts connect to each other. Security is a system, not isolated techniques.]
+
+```
+[Concept 1]
+    ↓
+  affects
+    ↓
+[Concept 2]
+    ↓
+  requires
+    ↓
+[Concept 3]
+```
+
+## Industry Standards and Frameworks
+
+### OWASP Top 10
+
+This project addresses:
+- **[OWASP Category]** - [Specific vulnerability and how this project handles it]
+- **[Another category]** - [How this project relates]
+
+### MITRE ATT&CK
+
+Relevant techniques:
+- **[Technique ID]** - [Technique name] - [How this project detects or prevents it]
+- **[Another technique]** - [Connection to the project]
+
+### CWE
+
+Common weakness enumerations covered:
+- **[CWE-XXX]** - [Weakness name] - [How this project demonstrates or prevents it]
+
+## Real World Examples
+
+### Case Study 1: [Actual Incident]
+
+[Describe a real breach or vulnerability that relates to these concepts. Include:
+- What happened
+- How the attack worked
+- What defenses failed
+- How this could have been prevented]
+
+### Case Study 2: [Another Example]
+
+[Another real world example]
+
+## Testing Your Understanding
+
+Before moving to the architecture, make sure you can answer:
+
+1. [Question that tests understanding of concept 1]
+2. [Question that requires applying concept 2]
+3. [Question that connects multiple concepts]
+
+If these questions feel unclear, re-read the relevant sections. The implementation will make more sense once these fundamentals click.
+
+## Further Reading
+
+**Essential:**
+- [Resource 1] - [Why this is valuable]
+- [Resource 2] - [What you'll get from it]
+
+**Deep dives:**
+- [Advanced resource 1] - [When to read this]
+- [Advanced resource 2] - [What this covers that we didn't]
+
+**Historical context:**
+- [Paper or talk] - [Why this matters for understanding the evolution]
diff --git a/.github/learn-folder-template/02-ARCHITECTURE.md b/.github/learn-folder-template/02-ARCHITECTURE.md
new file mode 100644
index 00000000..029fbc14
--- /dev/null
+++ b/.github/learn-folder-template/02-ARCHITECTURE.md
@@ -0,0 +1,370 @@
+# System Architecture
+
+This document breaks down how the system is designed and why certain architectural decisions were made.
+
+## High Level Architecture
+
+```
+[ASCII diagram showing major components and how they connect]
+
+Example:
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  Component  │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   Storage   │
+└─────────────┘
+```
+
+### Component Breakdown
+
+**[Component 1]**
+- Purpose: [What this component does]
+- Responsibilities: [Specific tasks it handles]
+- Interfaces: [How other components interact with it]
+
+**[Component 2]**
+- Purpose: [What this component does]
+- Responsibilities: [Specific tasks it handles]
+- Interfaces: [How other components interact with it]
+
+**[Component 3]**
+- Purpose: [What this component does]
+- Responsibilities: [Specific tasks it handles]
+- Interfaces: [How other components interact with it]
+
+## Data Flow
+
+### [Primary Use Case Flow]
+
+Step by step walkthrough of what happens when [primary operation]:
+
+```
+1. [Action] → [Component]
+   [What happens, what data is passed]
+
+2. [Component] → [Next component]
+   [Processing that occurs, transformations]
+
+3. [Next component] → [Result]
+   [Final output or state change]
+```
+
+Example with code references:
+```
+1. User sends request → API endpoint (src/routes/endpoint.py:42)
+   Validates input, extracts credentials
+
+2. API → Service layer (src/services/auth.py:108)
+   Business logic runs, queries database
+
+3. Service → Response (src/routes/endpoint.py:67)
+   Formats result, returns to user
+```
+
+### [Secondary Use Case Flow]
+
+[Repeat for other major operations]
+
+## Design Patterns
+
+### [Pattern 1 Used in Project]
+
+**What it is:**
+[Brief explanation of the pattern]
+
+**Where we use it:**
+[Specific files or components that implement this pattern]
+
+**Why we chose it:**
+[Advantages for this specific use case, alternatives considered]
+
+**Trade-offs:**
+- Pros: [What you gain]
+- Cons: [What you give up]
+
+Example implementation:
+```[language]
+[Code snippet showing the pattern in action from the actual project]
+```
+
+### [Pattern 2]
+
+[Same structure]
+
+## Layer Separation
+
+[If applicable - explain the layer architecture]
+
+```
+┌────────────────────────────────────┐
+│    Layer 1: [Name]                 │
+│    - [Responsibility]              │
+│    - [What it doesn't do]          │
+└────────────────────────────────────┘
+           ↓
+┌────────────────────────────────────┐
+│    Layer 2: [Name]                 │
+│    - [Responsibility]              │
+│    - [What it doesn't do]          │
+└────────────────────────────────────┘
+           ↓
+┌────────────────────────────────────┐
+│    Layer 3: [Name]                 │
+│    - [Responsibility]              │
+│    - [What it doesn't do]          │
+└────────────────────────────────────┘
+```
+
+### Why Layers?
+
+[Explain the benefits of this separation]
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+
+### What Lives Where
+
+**[Layer 1]:**
+- Files: [Which files belong to this layer]
+- Imports: [Can import from which other layers]
+- Forbidden: [What this layer should never do]
+
+**[Layer 2]:**
+[Same structure]
+
+**[Layer 3]:**
+[Same structure]
+
+## Data Models
+
+### [Model 1]
+
+```[language]
+[Actual data structure from the project]
+```
+
+**Fields explained:**
+- `[field_name]`: [What this stores, why it's needed, any constraints]
+- `[field_name]`: [Explanation]
+- `[field_name]`: [Explanation]
+
+**Relationships:**
+- [How this model connects to others]
+- [Why these relationships exist]
+
+### [Model 2]
+
+[Same structure for each major data model]
+
+## Security Architecture
+
+### Threat Model
+
+What we're protecting against:
+1. **[Threat 1]** - [Specific attack scenario]
+2. **[Threat 2]** - [Specific attack scenario]
+3. **[Threat 3]** - [Specific attack scenario]
+
+What we're NOT protecting against (out of scope):
+- [Thing 1] - [Why this is out of scope]
+- [Thing 2] - [Reason]
+
+### Defense Layers
+
+[Explain how security is implemented at different levels]
+
+```
+Layer 1: [Defense mechanism]
+    ↓
+Layer 2: [Defense mechanism]
+    ↓
+Layer 3: [Defense mechanism]
+```
+
+**Why multiple layers?**
+[Explain defense in depth for this specific project]
+
+## Storage Strategy
+
+### [Storage Type 1]
+
+**What we store:**
+- [Data type 1]
+- [Data type 2]
+
+**Why this storage:**
+[Explain choice - performance, durability, cost, etc]
+
+**Schema design:**
+```
+[Show key structure or table design]
+```
+
+### [Storage Type 2]
+
+[If using multiple storage backends]
+
+## Configuration
+
+### Environment Variables
+
+```bash
+[VARIABLE_NAME]  # [What it configures, default value, why you'd change it]
+[VARIABLE_NAME]  # [Explanation]
+```
+
+### Configuration Strategy
+
+[Explain how config is managed - files, env vars, secrets, etc]
+
+**Development:**
+[How config works in dev]
+
+**Production:**
+[How config works in prod, security considerations]
+
+## Performance Considerations
+
+### Bottlenecks
+
+Where this system gets slow under load:
+1. **[Bottleneck 1]** - [Why this happens, when it matters]
+2. **[Bottleneck 2]** - [Explanation]
+
+### Optimizations
+
+What we did to make it faster:
+- **[Optimization 1]**: [What we changed, impact it had]
+- **[Optimization 2]**: [Details]
+
+### Scalability
+
+**Vertical scaling:**
+[How to scale up - more CPU/RAM]
+[Where limits are]
+
+**Horizontal scaling:**
+[How to scale out - more instances]
+[What needs to change to support this]
+
+## Design Decisions
+
+### [Major Decision 1]
+
+**What we chose:**
+[The approach taken]
+
+**Alternatives considered:**
+- [Option A] - Rejected because [reason]
+- [Option B] - Rejected because [reason]
+
+**Trade-offs:**
+[What we gained and what we gave up with this choice]
+
+### [Major Decision 2]
+
+[Same structure for each significant architectural choice]
+
+## Deployment Architecture
+
+[If applicable - how this runs in production]
+
+```
+[Diagram showing deployment topology]
+```
+
+**Components:**
+- [Service 1]: [What it runs, how many instances, why]
+- [Service 2]: [Details]
+
+**Infrastructure:**
+- [Database/cache/etc]: [How it's deployed]
+
+## Error Handling Strategy
+
+### Error Types
+
+1. **[Error category 1]** - [What causes this, how we handle it]
+2. **[Error category 2]** - [Details]
+
+### Recovery Mechanisms
+
+[How the system recovers from failures]
+
+**[Failure scenario 1]:**
+- Detection: [How we know it happened]
+- Response: [What the system does]
+- Recovery: [How to get back to normal]
+
+## Extensibility
+
+### Where to Add Features
+
+Want to add [type of feature]? Here's where it goes:
+
+1. [Step 1 with file references]
+2. [Step 2]
+3. [Step 3]
+
+### Plugin Architecture
+
+[If applicable - how the system can be extended without modifying core code]
+
+## Limitations
+
+Current architectural limitations:
+1. **[Limitation 1]** - [What you can't do, why not, how to fix it]
+2. **[Limitation 2]** - [Details]
+
+These are not bugs, they're conscious trade-offs. Fixing them would require [what changes].
+
+## Comparison to Similar Systems
+
+### [Similar tool/approach 1]
+
+How we're different:
+- [Difference 1]
+- [Difference 2]
+
+Why we made different choices:
+[Reasoning specific to this use case]
+
+### [Similar tool/approach 2]
+
+[Same structure]
+
+## Evolution
+
+### Version 1.0 Design
+
+[If relevant - how the architecture has changed]
+
+Initial design was [approach]. We changed to current design because [reason].
+
+### Future Improvements
+
+Planned architectural changes:
+1. **[Improvement 1]** - [Why we want this, what it enables]
+2. **[Improvement 2]** - [Details]
+
+## Key Files Reference
+
+Quick map of where to find things:
+
+- `[file/directory]` - [What's implemented here]
+- `[file/directory]` - [Purpose]
+- `[file/directory]` - [What to look at]
+
+## Next Steps
+
+Now that you understand the architecture:
+1. Read [03-IMPLEMENTATION.md](./03-IMPLEMENTATION.md) for code walkthrough
+2. Try modifying [specific component] to understand [concept]
diff --git a/.github/learn-folder-template/03-IMPLEMENTATION.md b/.github/learn-folder-template/03-IMPLEMENTATION.md
new file mode 100644
index 00000000..0eedb41b
--- /dev/null
+++ b/.github/learn-folder-template/03-IMPLEMENTATION.md
@@ -0,0 +1,545 @@
+# Implementation Guide
+
+This document walks through the actual code. We'll build key features step by step and explain the decisions along the way.
+
+## File Structure Walkthrough
+
+```
+[project-name]/
+├── [directory]/
+│   ├── [file1]     # [What this implements]
+│   └── [file2]     # [What this implements]
+├── [directory]/
+│   └── [file]      # [What this implements]
+└── [key file]      # [What this implements]
+```
+
+## Building [Core Feature 1]
+
+### Step 1: [First Step]
+
+What we're building: [Specific functionality]
+
+Create `[filename]`:
+
+```[language]
+[Code with inline comments explaining the important parts]
+```
+
+**Why this code works:**
+- [Line/section 1]: [Explanation of what it does and why]
+- [Line/section 2]: [Explanation]
+- [Line/section 3]: [Explanation]
+
+**Common mistakes here:**
+```[language]
+# Wrong approach
+[Code showing what NOT to do]
+
+# Why this fails: [Explanation of the problem]
+```
+
+### Step 2: [Second Step]
+
+Now we need to [next functionality].
+
+In `[filename]` (lines XX-YY):
+
+```[language]
+[Relevant code snippet from the actual project]
+```
+
+**What's happening:**
+1. [Step by step breakdown]
+2. [Explanation]
+3. [Explanation]
+
+**Why we do it this way:**
+[Explain the reasoning - performance, security, maintainability, etc]
+
+**Alternative approaches:**
+- [Approach A]: Works but [drawback]
+- [Approach B]: Simpler but [limitation]
+
+### Step 3: [Third Step]
+
+[Continue pattern for each major step]
+
+## Building [Core Feature 2]
+
+### The Problem
+
+[Describe what challenge this feature solves]
+
+### The Solution
+
+[High level approach before diving into code]
+
+### Implementation
+
+In `[filename]`:
+
+```[language]
+[Code implementation]
+```
+
+**Key parts explained:**
+
+**[Function/class name]** (`[filename]:[line]`)
+```[language]
+[Focused code snippet]
+```
+This handles [specific responsibility]. The reason we [design choice] is because [explanation].
+
+**[Another function/class]** (`[filename]:[line]`)
+```[language]
+[Code snippet]
+```
+[Explanation of what this does differently and why]
+
+### Testing This Feature
+
+```[language]
+[Test code or example usage]
+```
+
+Expected output:
+```
+[What you should see]
+```
+
+If you see [error], it means [problem and fix].
+
+## Security Implementation
+
+### [Security Feature 1]
+
+File: `[filename]`
+
+```[language]
+[Security related code]
+```
+
+**What this prevents:**
+[Specific attack or vulnerability]
+
+**How it works:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**What happens if you remove this:**
+[Demonstrate why this security measure is necessary]
+
+### [Security Feature 2]
+
+[Same pattern for each security mechanism]
+
+## Data Flow Example
+
+Let's trace a complete request through the system.
+
+**Scenario:** [Specific user action]
+
+### Request Comes In
+
+```[language]
+# Entry point: [filename]:[line]
+[Code at entry point]
+```
+
+At this point:
+- [State/data description]
+- [What's been validated]
+- [What happens next]
+
+### Processing Layer
+
+```[language]
+# Processing: [filename]:[line]
+[Code in processing layer]
+```
+
+This code:
+- [Action 1]
+- [Action 2]
+- [Why it's structured this way]
+
+### Storage/Output
+
+```[language]
+# Final step: [filename]:[line]
+[Code that completes the operation]
+```
+
+The result is [outcome]. We store/return it as [format] because [reason].
+
+## Error Handling Patterns
+
+### [Error Type 1]
+
+When [condition] happens, we need to [response].
+
+```[language]
+# [filename]:[line]
+try:
+    [operation that might fail]
+except [SpecificException] as e:
+    [error handling]
+```
+
+**Why this specific handling:**
+[Explanation of the error handling strategy]
+
+**What NOT to do:**
+```[language]
+# Bad: catching everything
+try:
+    [operation]
+except Exception:
+    pass  # Silently fails - terrible idea
+```
+
+This hides actual problems. Always handle specific exceptions.
+
+### [Error Type 2]
+
+[Continue for major error cases]
+
+## Performance Optimizations
+
+### [Optimization 1]
+
+**Before:**
+```[language]
+[Slow/naive implementation]
+```
+
+This was slow because [reason]. With [example scenario], it took [time/resources].
+
+**After:**
+```[language]
+[Optimized implementation]
+```
+
+**What changed:**
+- [Change 1]: [Impact]
+- [Change 2]: [Impact]
+
+**Benchmarks:**
+- Before: [metric]
+- After: [metric]
+- Improvement: [percentage/factor]
+
+### [Optimization 2]
+
+[Same pattern]
+
+## Configuration Management
+
+### Loading Config
+
+```[language]
+# [filename]:[line]
+[Config loading code]
+```
+
+**Why this approach:**
+[Explain the config strategy]
+
+**Validation:**
+```[language]
+[Config validation code if applicable]
+```
+
+We validate early because [reason]. If config is wrong, we want to fail fast at startup, not mysteriously later.
+
+## Database/Storage Operations
+
+### [Operation Type 1]
+
+```[language]
+# [filename]:[line]
+[Database operation code]
+```
+
+**Important details:**
+- [Transaction handling]: [Why it matters]
+- [Connection management]: [How we avoid leaks]
+- [Query optimization]: [Why we wrote it this way]
+
+### Migrations
+
+[If applicable]
+
+When you change [data structure], run:
+```bash
+[migration command]
+```
+
+This updates [what changes] without losing [what's preserved].
+
+## Integration Points
+
+### [External System/API 1]
+
+How we integrate with [system]:
+
+```[language]
+# [filename]:[line]
+[Integration code]
+```
+
+**Authentication:**
+[How auth is handled]
+
+**Error handling:**
+[What happens when external system fails]
+
+**Rate limiting:**
+[How we avoid getting throttled]
+
+### [External System 2]
+
+[Same pattern]
+
+## Testing Strategy
+
+### Unit Tests
+
+Example test for [component]:
+
+```[language]
+# tests/[filename]
+[Test code]
+```
+
+**What this tests:**
+- [Behavior 1]
+- [Behavior 2]
+
+**Why these specific assertions:**
+[Explain what could break and how test catches it]
+
+### Integration Tests
+
+```[language]
+# tests/[filename]
+[Integration test code]
+```
+
+This tests [end-to-end scenario]. We need this because unit tests don't catch [specific integration issues].
+
+### Running Tests
+
+```bash
+[test command]
+```
+
+If tests fail with [error], check [common cause].
+
+## Common Implementation Pitfalls
+
+### Pitfall 1: [Common Mistake]
+
+**Symptom:**
+[What the developer sees]
+
+**Cause:**
+```[language]
+# The problematic code
+[What they probably wrote]
+```
+
+**Fix:**
+```[language]
+# Correct approach
+[How to do it right]
+```
+
+**Why this matters:**
+[Real impact of the mistake]
+
+### Pitfall 2: [Another Mistake]
+
+[Same pattern for common errors you actually see in this domain]
+
+## Debugging Tips
+
+### [Issue Type 1]
+
+**Problem:** [Description]
+
+**How to debug:**
+1. Check [location 1] for [evidence]
+2. Look at [logs/output] for [pattern]
+3. Verify [assumption]
+
+**Common causes:**
+- [Cause 1]
+- [Cause 2]
+
+### [Issue Type 2]
+
+[Continue for common debugging scenarios]
+
+## Code Organization Principles
+
+### Why [File/Module] is Structured This Way
+
+```
+[module]/
+├── [file1]  # [Responsibility]
+└── [file2]  # [Responsibility]
+```
+
+We separate [concern 1] from [concern 2] because:
+- [Reason 1]
+- [Reason 2]
+
+This makes [benefit].
+
+### Naming Conventions
+
+- `[pattern]` = [What this naming means]
+- `[pattern]` = [Convention explanation]
+
+Following these patterns makes it easier to [benefit].
+
+## Extending the Code
+
+### Adding a New [Feature Type]
+
+Want to add [capability]? Here's the process:
+
+1. **Create [component]** in `[location]`
+   ```[language]
+   [Template code to start from]
+   ```
+
+2. **Register [component]** in `[location]`
+   ```[language]
+   [Registration code]
+   ```
+
+3. **Add tests** in `[location]`
+   ```[language]
+   [Test template]
+   ```
+
+### Plugin Pattern
+
+[If applicable - how to extend without modifying core]
+
+Create `plugins/[name].py`:
+```[language]
+[Plugin template code]
+```
+
+The system discovers plugins by [mechanism]. Your plugin must implement [interface].
+
+## Code Style and Standards
+
+### Formatting
+
+We use [linter/formatter]:
+```bash
+[command to run it]
+```
+
+Key rules:
+- [Rule 1]: [Why]
+- [Rule 2]: [Why]
+
+### Type Annotations
+
+[If applicable]
+
+```[language]
+# Good
+[properly typed code]
+
+# Bad
+[untyped code]
+```
+
+Types catch [specific bugs] at [development stage] instead of [runtime].
+
+## Dependencies
+
+### Why Each Dependency
+
+- **[package1]** ([version]): [What we use it for, why this package specifically]
+- **[package2]** ([version]): [Purpose and reasoning]
+- **[package3]** ([version]): [Explanation]
+
+### Dependency Security
+
+Check for vulnerabilities:
+```bash
+[security scan command]
+```
+
+If you see [vulnerability type], [how to handle it].
+
+## Build and Deploy
+
+### Building
+
+```bash
+[build commands]
+```
+
+This produces [artifacts]. The build process:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Local Development
+
+```bash
+# Start development environment
+[dev command]
+
+# Hot reload is enabled - changes to [files] reload automatically
+```
+
+### Production Deployment
+
+[High level deployment process]
+
+Key differences from dev:
+- [Difference 1]
+- [Difference 2]
+
+## Performance Profiling
+
+### Finding Bottlenecks
+
+```bash
+[profiling command]
+```
+
+Look for:
+- [Metric 1] above [threshold] = [problem]
+- [Metric 2] indicates [bottleneck]
+
+### Memory Profiling
+
+[If relevant]
+
+```bash
+[memory profiling command]
+```
+
+Common memory leaks in this codebase:
+- [Pattern 1]: [How to spot and fix]
+- [Pattern 2]: [Details]
+
+## Next Steps
+
+You've seen how the code works. Now:
+
+1. **Try the challenges** - [04-CHALLENGES.md](./04-CHALLENGES.md) has extension ideas
+2. **Modify the code** - Change [component] to [variation] to test your understanding
+3. **Read related projects** - [Link to related project] builds on these concepts
diff --git a/.github/learn-folder-template/04-CHALLENGES.md b/.github/learn-folder-template/04-CHALLENGES.md
new file mode 100644
index 00000000..9ae64658
--- /dev/null
+++ b/.github/learn-folder-template/04-CHALLENGES.md
@@ -0,0 +1,420 @@
+# Extension Challenges
+
+You've built the base project. Now make it yours by extending it with new features.
+
+These challenges are ordered by difficulty. Start with the easier ones to build confidence, then tackle the harder ones when you want to dive deeper.
+
+## Easy Challenges
+
+### Challenge 1: [Extension Idea]
+
+**What to build:**
+[Specific feature to add]
+
+**Why it's useful:**
+[Real world scenario where this matters]
+
+**What you'll learn:**
+- [Skill/concept 1]
+- [Skill/concept 2]
+
+**Hints:**
+- Look at `[filename]` - you'll need to modify [component]
+- The key is [concept/technique]
+- Don't forget to handle [edge case]
+
+**Test it works:**
+[How to verify the feature works correctly]
+
+### Challenge 2: [Another Extension]
+
+[Same format for each challenge]
+
+### Challenge 3: [Another Extension]
+
+[Continue pattern]
+
+## Intermediate Challenges
+
+### Challenge 4: [More Complex Feature]
+
+**What to build:**
+[Feature description]
+
+**Real world application:**
+[Where you'd actually use this in production]
+
+**What you'll learn:**
+- [New concept 1]
+- [New concept 2]
+- [Integration with existing code]
+
+**Implementation approach:**
+
+1. **Add [component]** to handle [responsibility]
+   - Files to create: `[filename]`
+   - Files to modify: `[filename]`
+
+2. **Integrate with [existing system]**
+   - Hook into [entry point]
+   - Pass data through [flow]
+
+3. **Test edge cases:**
+   - What if [scenario 1]?
+   - How do you handle [scenario 2]?
+
+**Hints:**
+- You'll need [technology/library]
+- The tricky part is [specific challenge]
+- Consider [design pattern] for [aspect]
+
+**Extra credit:**
+[Additional variation to make it more sophisticated]
+
+### Challenge 5: [Another Intermediate Feature]
+
+[Continue pattern]
+
+## Advanced Challenges
+
+### Challenge 6: [Complex Integration]
+
+**What to build:**
+[Significant new capability]
+
+**Why this is hard:**
+[What makes this challenging - multiple components, complex state, performance, etc]
+
+**What you'll learn:**
+- [Advanced concept 1]
+- [Advanced concept 2]
+- [System design skill]
+
+**Architecture changes needed:**
+
+```
+[Diagram showing how the new feature fits in]
+```
+
+**Implementation steps:**
+
+1. **Research phase**
+   - Read about [technology/concept]
+   - Understand [standard/protocol/algorithm]
+   - Look at [reference implementation]
+
+2. **Design phase**
+   - Decide between [approach A] vs [approach B]
+   - Consider impact on [existing component]
+   - Plan database/storage changes
+
+3. **Implementation phase**
+   - Start with [minimal version]
+   - Add [capability 1]
+   - Add [capability 2]
+
+4. **Testing phase**
+   - Unit test [component]
+   - Integration test [flow]
+   - Performance test under [load scenario]
+
+**Gotchas:**
+- [Common mistake 1]: [How to avoid]
+- [Common mistake 2]: [How to avoid]
+
+**Resources:**
+- [RFC/spec/documentation] - [What to focus on]
+- [Blog post/paper] - [Key insights]
+
+### Challenge 7: [Another Advanced Feature]
+
+[Continue pattern]
+
+## Expert Challenges
+
+### Challenge 8: [Major Feature Requiring Significant Work]
+
+**What to build:**
+[Ambitious extension that changes how the system works]
+
+**Estimated time:**
+[Realistic estimate - days or weeks]
+
+**Prerequisites:**
+You should have completed [earlier challenges] first because this builds on [concepts].
+
+**What you'll learn:**
+- [Expert level concept 1]
+- [Expert level concept 2]
+- [Real world engineering skill]
+
+**Planning this feature:**
+
+Before you code, think through:
+- How does this affect existing functionality?
+- What are the performance implications?
+- How do you migrate existing data/users?
+- What's your rollback plan if it breaks?
+
+**High level architecture:**
+
+```
+[Detailed architecture diagram of the new feature]
+```
+
+**Implementation phases:**
+
+**Phase 1: Foundation** (X-Y hours)
+- [What to build first]
+- [Why this order]
+
+**Phase 2: Core Feature** (X-Y hours)
+- [Main functionality]
+- [Key algorithms/logic]
+
+**Phase 3: Integration** (X-Y hours)
+- [Connect to existing system]
+- [Handle compatibility]
+
+**Phase 4: Polish** (X-Y hours)
+- [Error handling]
+- [Performance optimization]
+- [Documentation]
+
+**Testing strategy:**
+- [Test type 1]: [What to verify]
+- [Test type 2]: [Scenarios to cover]
+- [Test type 3]: [Edge cases]
+
+**Known challenges:**
+1. **[Challenge 1]**
+   - Problem: [What goes wrong]
+   - Hint: [Direction toward solution]
+
+2. **[Challenge 2]**
+   - Problem: [Issue]
+   - Hint: [Guidance]
+
+**Success criteria:**
+Your implementation should:
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+- [ ] Handle [edge case]
+- [ ] Pass [performance benchmark]
+
+### Challenge 9: [Another Expert Challenge]
+
+[Continue pattern]
+
+## Mix and Match
+
+Combine features for bigger projects:
+
+**Project Idea 1: [Combined Feature Set]**
+- Combine Challenge X + Challenge Y
+- Add [new integration]
+- Result: [What you end up with]
+
+**Project Idea 2: [Another Combination]**
+- [Details]
+
+## Real World Integration Challenges
+
+### Integrate with [External System/API]
+
+**The goal:**
+Make this project work with [real service].
+
+**What you'll need:**
+- [Service] account/API key
+- Understanding of [protocol/API]
+- Handle [authentication method]
+
+**Implementation plan:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Watch out for:**
+- [Rate limits]
+- [Authentication refresh]
+- [Error handling]
+
+### Deploy to [Platform]
+
+**The goal:**
+Get this running in production on [cloud platform/service].
+
+**What you'll learn:**
+- [Infrastructure as code]
+- [Deployment automation]
+- [Production monitoring]
+
+**Steps:**
+1. [Infrastructure setup]
+2. [Configuration management]
+3. [Deployment pipeline]
+4. [Monitoring setup]
+
+**Production checklist:**
+- [ ] [Security requirement]
+- [ ] [Performance requirement]
+- [ ] [Monitoring requirement]
+- [ ] [Backup/recovery]
+
+## Performance Challenges
+
+### Challenge: Handle [Scale Metric]
+
+**The goal:**
+Make this system handle [specific load] without falling over.
+
+**Current bottleneck:**
+[Component] can only handle [current limit] because [reason].
+
+**Optimization approaches:**
+
+**Approach 1: [Technique]**
+- How: [Implementation]
+- Gain: [Performance improvement]
+- Tradeoff: [What you give up]
+
+**Approach 2: [Another technique]**
+- How: [Details]
+- Gain: [Improvement]
+- Tradeoff: [Cost]
+
+**Benchmark it:**
+```bash
+[Load testing command]
+```
+
+Target metrics:
+- [Metric 1]: [Goal]
+- [Metric 2]: [Goal]
+
+### Challenge: Reduce [Resource Usage]
+
+**The goal:**
+Cut [memory/CPU/bandwidth] usage by [percentage].
+
+**Profile first:**
+```bash
+[profiling command]
+```
+
+**Common optimization areas:**
+- [Area 1]: [What's inefficient, how to fix]
+- [Area 2]: [Details]
+
+## Security Challenges
+
+### Challenge: Add [Security Feature]
+
+**What to implement:**
+[Specific security mechanism]
+
+**Threat model:**
+This protects against:
+- [Attack 1]
+- [Attack 2]
+
+**Implementation:**
+[Where to add it, how it works]
+
+**Testing the security:**
+- Try to [bypass method 1]
+- Attempt [attack vector 2]
+- Verify [security property holds]
+
+### Challenge: Pass [Security Standard]
+
+**The goal:**
+Make this project compliant with [OWASP/CIS/NIST standard].
+
+**Current gaps:**
+- [Gap 1]: [What's missing]
+- [Gap 2]: [What needs fixing]
+
+**Remediation:**
+[How to address each gap]
+
+## Contribution Ideas
+
+Finished a challenge? Share it back:
+
+1. **Fork the repo**
+2. **Implement your extension** in a new branch
+3. **Document it** - add to learn folder
+4. **Submit a PR** with:
+   - Your implementation
+   - Tests
+   - Documentation
+   - Example usage
+
+Good extensions might get merged into the main project.
+
+## Challenge Yourself Further
+
+### Build Something New
+
+Use the concepts you learned here to build:
+- [Related tool 1] - [What it would do]
+- [Related tool 2] - [Purpose]
+- [Variation] - [How it's different]
+
+### Study Real Implementations
+
+Compare your implementation to production tools:
+- [Tool 1] - [What they do differently]
+- [Tool 2] - [Interesting design choices]
+
+Read their code, understand their tradeoffs, steal their good ideas.
+
+### Write About It
+
+Document your extension:
+- Blog post explaining [what you built]
+- Tutorial for others to follow
+- Comparison with [alternative approach]
+
+Teaching others is the best way to verify you understand it.
+
+## Getting Help
+
+Stuck on a challenge?
+
+1. **Debug systematically**
+   - What did you expect?
+   - What actually happened?
+   - What's the smallest test case that reproduces it?
+
+2. **Read the existing code**
+   - [Similar feature] does something related
+   - [Component] might have the pattern you need
+
+3. **Search for similar problems**
+   - [Forum/community]
+   - [Stack Overflow tag]
+
+4. **Ask for help**
+   - Post in [discussion forum]
+   - Include: what you tried, what happened, what you expected
+   - Don't just paste error messages - explain your understanding
+
+## Challenge Completion
+
+Track your progress:
+
+- [ ] Easy Challenge 1
+- [ ] Easy Challenge 2
+- [ ] Easy Challenge 3
+- [ ] Intermediate Challenge 4
+- [ ] Intermediate Challenge 5
+- [ ] Advanced Challenge 6
+- [ ] Advanced Challenge 7
+- [ ] Expert Challenge 8
+- [ ] Expert Challenge 9
+
+Completed all of them? You've mastered this project. Time to build something new or contribute back to the community.
diff --git a/.github/learn-folder-template/CHECKLIST.md b/.github/learn-folder-template/CHECKLIST.md
new file mode 100644
index 00000000..8bee7659
--- /dev/null
+++ b/.github/learn-folder-template/CHECKLIST.md
@@ -0,0 +1,116 @@
+# Learn Folder Checklist
+
+Quick reference for what to include in each file.
+
+## 00-OVERVIEW.md
+
+- [ ] **What This Is** - 2-3 sentence project description
+- [ ] **Why This Matters** - Real world problem it solves
+- [ ] **Real world scenarios** - 3 specific use cases
+- [ ] **What You'll Learn** - Security concepts, technical skills, tools
+- [ ] **Prerequisites** - Required knowledge, tools needed, nice-to-haves
+- [ ] **Quick Start** - Installation steps that work
+- [ ] **Project Structure** - Key directories and files
+- [ ] **Next Steps** - Links to other learn files
+- [ ] **Common Issues** - 2-3 frequent problems with solutions
+- [ ] **Related Projects** - Links to similar projects
+
+## 01-CONCEPTS.md
+
+- [ ] **Primary Concept** - What it is, why it matters, how it works
+- [ ] **Common Attacks** - 3+ specific attack techniques
+- [ ] **Defense Strategies** - How to protect against attacks
+- [ ] **Secondary Concept** - Same structure
+- [ ] **Common Pitfalls** - Code examples of mistakes vs correct approach
+- [ ] **How Concepts Relate** - Connection diagram
+- [ ] **Industry Standards** - OWASP, MITRE, CWE mappings
+- [ ] **Real World Examples** - 2+ actual incidents/breaches
+- [ ] **Testing Your Understanding** - 3+ questions
+- [ ] **Further Reading** - Essential and deep dive resources
+
+## 02-ARCHITECTURE.md
+
+- [ ] **High Level Architecture** - ASCII diagram with components
+- [ ] **Component Breakdown** - Purpose and responsibilities of each
+- [ ] **Data Flow** - Step by step walkthrough with code references
+- [ ] **Design Patterns** - Patterns used, why, trade-offs
+- [ ] **Layer Separation** - If applicable, explain layers
+- [ ] **Data Models** - Key structures with field explanations
+- [ ] **Security Architecture** - Threat model and defense layers
+- [ ] **Storage Strategy** - What's stored where and why
+- [ ] **Configuration** - Environment variables and strategy
+- [ ] **Performance Considerations** - Bottlenecks and optimizations
+- [ ] **Design Decisions** - Major choices, alternatives, trade-offs
+- [ ] **Deployment Architecture** - How it runs in production
+- [ ] **Error Handling** - Strategy for different error types
+- [ ] **Extensibility** - Where and how to add features
+- [ ] **Limitations** - Current architectural constraints
+- [ ] **Comparison** - How this differs from similar systems
+
+## 03-IMPLEMENTATION.md
+
+- [ ] **File Structure** - Walkthrough of directory layout
+- [ ] **Building Core Feature 1** - Step by step with code
+- [ ] **Building Core Feature 2** - Same structure
+- [ ] **Security Implementation** - How security features work
+- [ ] **Data Flow Example** - Complete request trace through system
+- [ ] **Error Handling** - Patterns with code examples
+- [ ] **Performance Optimizations** - Before/after with benchmarks
+- [ ] **Configuration Management** - Loading and validation
+- [ ] **Database Operations** - CRUD with transaction handling
+- [ ] **Integration Points** - External systems/APIs
+- [ ] **Testing Strategy** - Unit and integration test examples
+- [ ] **Common Pitfalls** - Mistakes with symptoms, causes, fixes
+- [ ] **Debugging Tips** - How to troubleshoot common issues
+- [ ] **Code Organization** - Why files structured this way
+- [ ] **Extending the Code** - Template for adding features
+- [ ] **Code Style** - Linting, formatting, type annotations
+- [ ] **Dependencies** - Why each dependency, security scanning
+- [ ] **Build and Deploy** - Commands for building and running
+
+## 04-CHALLENGES.md
+
+- [ ] **Easy Challenges** (3+) - Simple extensions with hints
+- [ ] **Intermediate Challenges** (2+) - More complex features
+- [ ] **Advanced Challenges** (2+) - Significant new capabilities
+- [ ] **Expert Challenges** (1+) - Major features with detailed planning
+- [ ] **Mix and Match** - Combined project ideas
+- [ ] **Real World Integration** - External system connections
+- [ ] **Performance Challenges** - Scale and optimization tasks
+- [ ] **Security Challenges** - Additional security features
+- [ ] **Contribution Ideas** - How to share back
+- [ ] **Challenge Yourself Further** - Build new things, study others
+- [ ] **Getting Help** - Debugging and asking for help
+- [ ] **Challenge Completion** - Checklist to track progress
+
+## For Each Challenge
+
+- [ ] **What to build** - Specific feature description
+- [ ] **Why it's useful** - Real world application
+- [ ] **What you'll learn** - Skills and concepts
+- [ ] **Hints** - Guidance without full solution
+- [ ] **Test it works** - Verification steps
+
+## Writing Quality Checks
+
+- [ ] No em dashes (use periods or commas)
+- [ ] Minimal "it's not X, it's Y" contrast flips
+- [ ] Inconsistent hyphenation (mix it up)
+- [ ] Concrete examples, not abstractions
+- [ ] Real code from the project (not toy examples)
+- [ ] File and line number references
+- [ ] ASCII diagrams where helpful
+- [ ] Real world incidents referenced
+- [ ] Common mistakes shown
+- [ ] Human voice (not AI marketing speak)
+
+## Before Publishing
+
+- [ ] All links work
+- [ ] Code examples tested
+- [ ] Quick start instructions verified
+- [ ] Consistent formatting
+- [ ] No placeholder text left
+- [ ] Reviewed by someone else if possible
+- [ ] Spelling and grammar checked
+- [ ] Makes sense to someone unfamiliar with the project
diff --git a/.github/learn-folder-template/README.md b/.github/learn-folder-template/README.md
new file mode 100644
index 00000000..30f9aaa7
--- /dev/null
+++ b/.github/learn-folder-template/README.md
@@ -0,0 +1,264 @@
+# Learn Folder Template
+
+This directory contains templates for creating consistent, high quality educational documentation for each project.
+
+## What Goes in a learn/ Folder
+
+Every completed project should have a `learn/` directory with these four files:
+
+1. **00-OVERVIEW.md** - Project introduction, prerequisites, quick start
+2. **01-CONCEPTS.md** - Security concepts and theory
+3. **02-ARCHITECTURE.md** - System design and technical decisions
+4. **03-IMPLEMENTATION.md** - Code walkthrough and how to build it
+5. **04-CHALLENGES.md** - Extension ideas and next steps
+
+## Using These Templates
+
+### For New Projects
+
+When you start a new project:
+
+1. Copy this entire template directory to your project:
+   ```bash
+   cp -r .github/learn-folder-template PROJECTS/[difficulty]/[project-name]/learn
+   cd PROJECTS/[difficulty]/[project-name]/learn
+   ```
+
+2. Remove this README (you don't need it in the project):
+   ```bash
+   rm README.md
+   ```
+
+3. Fill in each template:
+   - Replace `[placeholders]` with actual content
+   - Delete sections that don't apply
+   - Add sections specific to your project
+   - Keep the overall structure
+
+4. Write as you build - don't wait until the end
+
+### For Existing Projects
+
+Backfilling learn/ folders:
+
+1. Start with 00-OVERVIEW.md - this is the easiest
+2. Then do 01-CONCEPTS.md - what security ideas does this teach?
+3. Then 02-ARCHITECTURE.md - how is it designed?
+4. Then 03-IMPLEMENTATION.md - walk through the actual code
+5. Finally 04-CHALLENGES.md - how can others extend it?
+
+Don't try to do all files at once. One file per session works fine.
+
+## Writing Guidelines
+
+### Tone and Style
+
+**Do:**
+- Write like you're explaining to a smart friend
+- Use concrete examples and real code
+- Explain WHY, not just WHAT
+- Reference actual vulnerabilities and incidents
+- Show common mistakes and how to avoid them
+- Use diagrams and code snippets liberally
+
+**Don't:**
+- Sound like a marketing brochure
+- Use buzzwords without explaining them
+- Assume the reader knows everything (or nothing)
+- Write walls of text - break it up
+- Skip the hard parts
+
+### Content Depth
+
+**00-OVERVIEW.md** - Surface level, get them excited and oriented
+- 5-10 minute read
+- Focus on what and why
+- Light on technical details
+
+**01-CONCEPTS.md** - Medium depth, teach the theory
+- 15-20 minute read
+- Explain security concepts thoroughly
+- Use examples and diagrams
+- Reference standards (OWASP, MITRE, etc)
+
+**02-ARCHITECTURE.md** - Deep dive on system design
+- 20-30 minute read
+- Show the big picture
+- Explain design decisions and tradeoffs
+- Include diagrams
+
+**03-IMPLEMENTATION.md** - Deepest, actual code walkthrough
+- 30-45 minute read
+- Reference real files and line numbers
+- Show actual code from the project
+- Explain step by step
+
+**04-CHALLENGES.md** - Mixed depth based on difficulty
+- 10-15 minute read
+- Range from easy to expert
+- Provide hints, not full solutions
+- Encourage experimentation
+
+### Code Examples
+
+Always show real code from the actual project, not toy examples:
+
+```python
+# Good - actual code from the project
+# src/auth/service.py:42-56
+async def authenticate_user(email: str, password: str) -> User:
+    user = await user_repo.find_by_email(email)
+    if not user or not verify_password(password, user.password_hash):
+        raise InvalidCredentials()
+    return user
+```
+
+```python
+# Bad - generic example
+def login(username, password):
+    # check if valid
+    return user
+```
+
+### Avoiding AI Voice
+
+Watch out for these telltale AI patterns:
+
+**Em dashes** - Don't use them. Use periods or commas instead.
+```
+Bad: "It's not just about security — it's about building robust systems"
+Good: "This teaches security and system design"
+```
+
+**Contrast flips** - The "it's not X, it's Y" pattern
+```
+Bad: "It's not about memorizing syntax — it's about understanding concepts"
+Good: "Focus on understanding concepts, not memorizing syntax"
+```
+
+**Perfect hyphenation** - Don't hyphenate every compound modifier
+```
+Bad: "real-time analysis using state-of-the-art machine-learning algorithms"
+Good: "real-time analysis using state of the art machine learning algorithms"
+```
+
+Mix it up. Sometimes hyphenate, sometimes don't. Humans are inconsistent.
+
+**Generic enthusiasm**
+```
+Bad: "Embark on an exciting journey into the world of cybersecurity!"
+Good: "Learn how rate limiting works by building one from scratch"
+```
+
+### Diagrams
+
+ASCII diagrams work great:
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│     API     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  Database   │
+└─────────────┘
+```
+
+Use them for:
+- Architecture overviews
+- Data flow
+- State machines
+- Layer diagrams
+
+### Real World References
+
+Ground concepts in reality:
+
+**Good:**
+"In the 2017 Equifax breach, attackers exploited a known Apache Struts vulnerability (CVE-2017-5638). This project teaches you how to scan for such vulnerabilities in your dependencies."
+
+**Bad:**
+"In today's evolving threat landscape, vulnerability management is critical."
+
+## Quality Checklist
+
+Before submitting a learn/ folder, check:
+
+### 00-OVERVIEW.md
+- [ ] Explains what the project does in 2-3 sentences
+- [ ] Lists specific prerequisites with examples
+- [ ] Includes quick start instructions that work
+- [ ] Shows expected output
+- [ ] Links to other learn/ files
+
+### 01-CONCEPTS.md
+- [ ] Explains each security concept thoroughly
+- [ ] Includes real world examples or breaches
+- [ ] Shows common attacks and defenses
+- [ ] References OWASP/MITRE/CWE where relevant
+- [ ] Includes "testing your understanding" questions
+
+### 02-ARCHITECTURE.md
+- [ ] High level architecture diagram
+- [ ] Component breakdown
+- [ ] Design decisions with reasoning
+- [ ] Data flow examples
+- [ ] Performance and security considerations
+
+### 03-IMPLEMENTATION.md
+- [ ] References actual files and line numbers
+- [ ] Shows real code from the project
+- [ ] Explains WHY, not just WHAT
+- [ ] Includes common pitfalls
+- [ ] Provides debugging tips
+
+### 04-CHALLENGES.md
+- [ ] Mix of difficulty levels
+- [ ] Specific, actionable challenges
+- [ ] Hints without full solutions
+- [ ] Real world applications
+- [ ] Connection to other projects
+
+### General
+- [ ] No em dashes
+- [ ] Minimal "it's not X, it's Y" patterns
+- [ ] Inconsistent hyphenation (like a human)
+- [ ] Concrete examples, not abstractions
+- [ ] Code examples are real, not toys
+- [ ] Diagrams where helpful
+- [ ] Links work
+- [ ] Formatting is consistent
+
+## Examples
+
+Good examples to reference:
+
+- **PROJECTS/advanced/bug-bounty-platform/learn/** - Comprehensive, well structured
+- **PROJECTS/advanced/api-rate-limiter/learn/** - Good technical depth
+
+These aren't perfect but they're solid templates to learn from.
+
+## Getting Help
+
+Questions about writing learn/ docs?
+
+1. Look at existing examples
+2. Ask in discussions
+3. Draft one file and get feedback before doing all five
+4. Iterate based on feedback
+
+## Contributing Improvements
+
+Found ways to improve these templates?
+
+1. Make changes to `.github/learn-folder-template/`
+2. Submit PR with explanation
+3. Update this README if structure changes
+
+The templates should evolve as we learn what works best.