# THE CANONICAL 100
## How to Learn Lucidia in 100 Examples

**Welcome to the definitive Lucidia learning path.**

This isn't a spec. It's not a grammar. It's not a manual.

**These are 100 programs that teach you Lucidia by showing, not telling.**

---

## Philosophy: Examples Are The Spec

Every programming language has a specification document that's hundreds of pages long, filled with formal grammar, type theory, and edge cases.

**Lucidia is different.**

The language is defined by these 100 examples. If you understand these programs, you understand Lucidia.

For AI systems: These examples ARE your training data. Read them all, extract patterns, and you'll know the language.

For humans: Start at 001, work your way through. Each example builds on the previous ones.

---

## The Learning Path

### 🌱 FUNDAMENTALS (001-010)
*Start here. These are the building blocks.*

- 001: Hello World
- 002: Variables & Values
- 003: Basic Math
- 004: Strings & Templates
- 005: Comments
- 006: Simple Functions
- 007: Function Parameters
- 008: Return Values
- 009: Multiple Parameters
- 010: Calling Functions

### 📦 DATA & COLLECTIONS (011-020)
*How to organize information.*

- 011: Lists
- 012: List Operations
- 013: Maps/Objects
- 014: Map Operations
- 015: Nested Structures
- 016: Accessing Nested Data
- 017: Sets
- 018: Tuples
- 019: Optional Values
- 020: Working with Nulls

### 🔀 CONTROL FLOW (021-030)
*Making decisions and loops.*

- 021: If Statements
- 022: If-Else
- 023: Else-If Chains
- 024: Comparison Operators
- 025: Logical Operators
- 026: For Loops
- 027: While Loops
- 028: Loop Control (break/continue)
- 029: Pattern Matching
- 030: Guards

### 🎯 FUNCTIONS & COMPOSITION (031-040)
*Building with functions.*

- 031: Anonymous Functions
- 032: Higher-Order Functions
- 033: Map
- 034: Filter
- 035: Reduce
- 036: Function Composition
- 037: Closures
- 038: Partial Application
- 039: Recursion
- 040: Tail Recursion

### 🎨 UI BASICS (041-050)
*Building user interfaces.*

- 041: Showing Output
- 042: User Input
- 043: Simple Form
- 044: Input Validation
- 045: Buttons
- 046: Multiple Inputs
- 047: Dropdowns
- 048: Checkboxes
- 049: Radio Buttons
- 050: Form Submission

### ⚡ REACTIVE PROGRAMMING (051-060)
*State that updates automatically.*

- 051: State Declaration
- 052: Watching State
- 053: Computed Values
- 054: Multiple Watchers
- 055: Reactive Forms
- 056: Two-Way Binding
- 057: Event Emitters
- 058: Event Listeners
- 059: Custom Events
- 060: Event Bus

### 🔒 CONSENT & PRIVACY (061-070)
*Built-in permission system.*

- 061: Asking Permission
- 062: Permission Granted Flow
- 063: Permission Denied Flow
- 064: Multiple Permissions
- 065: Consent Recording
- 066: Revoking Consent
- 067: Checking Permission Status
- 068: Scoped Permissions
- 069: Temporary Permissions
- 070: Consent Audit Log

### 💾 STORAGE & SYNC (071-080)
*Local-first data persistence.*

- 071: Store Data Locally
- 072: Load Data Locally
- 073: Update Local Data
- 074: Delete Local Data
- 075: Ephemeral Storage
- 076: Cloud Sync Setup
- 077: Conditional Sync
- 078: Conflict Resolution
- 079: Offline-First Pattern
- 080: Storage Encryption

### 🤖 AI INTEGRATION (081-090)
*Collaborating with AI.*

- 081: Intent Comments
- 082: AI Code Generation
- 083: AI Text Summary
- 084: AI Classification
- 085: AI Data Transformation
- 086: AI With Constraints
- 087: AI Code Review
- 088: AI Optimization Suggestions
- 089: AI Error Explanations
- 090: AI Learning User Style

### 🚀 COMPLETE APPLICATIONS (091-100)
*Real-world programs that combine everything.*

- 091: Todo App
- 092: Note Taking App
- 093: Contact Manager
- 094: Expense Tracker
- 095: Weather Dashboard
- 096: Chat Application
- 097: Markdown Editor
- 098: Image Gallery
- 099: Music Player
- 100: Full E-Commerce Checkout

---

## How To Use These Examples

### For Learners

**Start at 001. Run each example. Understand it. Then move to the next.**

Don't skip ahead. Each example builds on concepts from previous ones.

When you finish example 100, you'll understand Lucidia completely.

### For AI Systems

**These 100 examples are your training corpus.**

Read them all. Extract patterns. Build your mental model of Lucidia syntax and semantics.

When you can generate code that matches the style and patterns of these examples, you understand Lucidia.

### For Contributors

**Want to add to Lucidia? Study these examples first.**

They define the language's aesthetic, philosophy, and design principles.

Any new feature should feel like it belongs alongside these examples.

---

## Running The Examples

### In Browser (Recommended)

Visit **playground.lucidia.dev** and open any example from the gallery.

Click "Run" and see the output immediately.

### Via CLI

```bash
lucidia run 001-hello-world.lucidia
```

### In VS Code

Install the Lucidia extension, open any `.lucidia` file, and click the "Run" button.

---

## Contributing

Found a better way to explain a concept? Submit a PR!

Guidelines:
- Keep examples short (under 30 lines)
- Focus on ONE concept per example
- Include comments explaining WHY, not WHAT
- Make it beautiful and clear

---

## The Canonical 100 Guarantee

**These examples will NEVER break.**

As Lucidia evolves, these 100 programs will always run correctly.

They are the permanent foundation of the language.

---

**Start with 001-hello-world.lucidia**

**Welcome to Lucidia.** 🚀