docs: update documentation to reflect actual implementation status

Many features were documented as "missing" or "planned" but are actually
working: generics, string interpolation, File/HTTP/Random/Time effects,
JSON parsing, module system, and JIT CLI integration.

Updated IMPLEMENTATION_PLAN.md, OVERVIEW.md with accurate status.
Added ROADMAP.md (use-case-targeted) and LANGUAGE_COMPARISON.md.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/IMPLEMENTATION_PLAN.md

@@ -2,7 +2,7 @@
 
 ## Current Status Summary
 
-### What's Working (147 tests passing)
+### What's Working (150+ tests passing)
 
 **Core Language:**
 - Lexer and parser for core syntax
@@ -16,6 +16,9 @@
 - Higher-order functions and closures
 - Pipe operator (`|>`)
 - Documentation comments
+- **Generic type parameters** (`fn map<T, U>`, `type List<T>`)
+- **String interpolation** (`"Hello {name}!"`)
+- **Escape sequences** (`\n`, `\t`, `\"`, `\{`, `\}`)
 
 **Effect System:**
 - Effect declarations
@@ -25,6 +28,13 @@
 - Effect inference within function bodies
 - Effect subset checking (pure functions callable in effectful contexts)
 
+**Built-in Effects:**
+- `Console` - print, readLine, readInt
+- `File` - read, write, exists, delete, listDir, createDir
+- `Http` - get, post
+- `Random` - int, float, range, bool, element
+- `Time` - now, sleep
+
 **Type Classes:**
 - Trait declarations
 - Implementation blocks
@@ -33,11 +43,34 @@
 **Behavioral Properties:**
 - Property declarations (`is pure`, `is idempotent`, etc.)
 - Property parsing and storage in AST
+- Pure function verification (no effects allowed)
+
+**Module System:**
+- Import/export with `pub` visibility
+- Aliased imports (`import foo as bar`)
+- Selective imports (`import foo.{a, b}`)
+- Wildcard imports (`import foo.*`)
+- Circular dependency detection
+- Transitive imports
+
+**JIT Compiler (Cranelift):**
+- Integer arithmetic and comparisons
+- Conditionals, let bindings, blocks
+- Function calls including recursion
+- ~160x speedup over interpreter for numeric code
+- CLI integration via `lux compile <file>`
+
+**Standard Library:**
+- String operations (substring, length, split, trim, etc.)
+- List operations (map, filter, fold, etc.)
+- JSON parsing and serialization
+- Math functions
 
 **Tooling:**
 - REPL with history and autocomplete
 - LSP server (diagnostics, hover, completions)
-- Elm-style error messages
+- Watch mode for auto-recompilation
+- Source-context error messages
 
 ### Example Programs Working
 1. `hello.lux` - Basic effect usage
@@ -50,6 +83,13 @@
 8. `tailcall.lux` - Tail call optimization
 9. `statemachine.lux` - State machines with ADTs
 10. `pipelines.lux` - Pipe operator
+11. `generics.lux` - Generic type parameters
+12. `json.lux` - JSON parsing and serialization
+13. `jit_test.lux` - JIT compilation demo
+14. `guessing_game.lux` - Console input/output
+15. `examples/modules/main.lux` - Module imports
+16. `examples/modules/main_selective.lux` - Selective imports
+17. `examples/modules/main_wildcard.lux` - Wildcard imports
 
 ---
 
@@ -58,46 +98,42 @@
 ### Priority 1: Critical Missing Features
 
 #### 1.1 Generic Type Parameters
-**Status:** Parser supports `Option<Int>` syntax but type system doesn't fully support generics.
+**Status:** ✅ Complete
 
-**What's Missing:**
+Generic type parameters are fully working:
 - Type parameter declarations in type definitions (`type List<T> = ...`)
-- Type application in type checking
 - Generic function parameters (`fn map<T, U>(f: fn(T): U, list: List<T>): List<U>`)
+- Type application and instantiation
+- See `examples/generics.lux` for working examples
+
+**Still Missing (nice-to-have):**
 - Type parameter constraints (`where T: Eq`)
 
-**Implementation Steps:**
-1. Add type parameter support to type definitions in AST
-2. Implement kind checking (types vs type constructors)
-3. Add type application rules to unification
-4. Support polymorphic function instantiation
-
 #### 1.2 String Interpolation
-**Status:** Not implemented. Currently requires manual `toString()` calls.
+**Status:** ✅ Complete
 
-**What's Missing:**
-- Parser support for `"Hello, {name}!"` syntax
-- Type checking for interpolated expressions
-- Runtime string building
-
-**Implementation Steps:**
-1. Add string interpolation tokens to lexer
-2. Parse interpolated strings into AST (list of parts)
-3. Desugar to string concatenation
+String interpolation is fully working:
+- `"Hello, {name}!"` syntax
+- Nested expressions: `"Result: {1 + 2}"`
+- Escape sequences: `\{`, `\}`, `\n`, `\t`, `\"`, `\\`
 
 #### 1.3 Better Error Messages
-**Status:** Basic error messages exist but can be improved.
+**Status:** ⚠️ Partial
+
+**What's Working:**
+- Source code context with line/column numbers
+- Caret pointing to error location
+- Color-coded error output
 
 **What's Missing:**
-- Source code context in all errors
 - Type diff display for mismatches
-- Suggestions for common mistakes
+- "Did you mean?" suggestions
 - Error recovery in parser
 
 **Implementation Steps:**
-1. Ensure all errors include span information
+1. Add Levenshtein distance for suggestions
 2. Implement error recovery in parser
-3. Add "did you mean?" suggestions
+3. Add type diff visualization
 
 ### Priority 2: Effect System Completion
 
@@ -120,20 +156,25 @@ fn withRetry<E>(action: fn(): T with E, attempts: Int): T with E = ...
 3. Support effect quantification in type schemes
 
 #### 2.2 Built-in Effects
-**Status:** Only Console effect is built-in.
+**Status:** ⚠️ Partial - Several working, some missing
+
+**Working Effects:**
+- `Console` - print, readLine, readInt
+- `File` - read, write, exists, delete, listDir, createDir
+- `Http` - get, post
+- `Random` - int, float, range, bool, element
+- `Time` - now, sleep
 
 **Missing Effects:**
-- `State<S>` - get/put state
+- `State<S>` - get/put state (generic over state type)
 - `Reader<R>` - read-only environment
 - `Fail` - early returns/exceptions
-- `Random` - random number generation
-- `Time` - current time, delays
 - `Async` - async/await
 
 **Implementation Steps:**
-1. Define effect interfaces in prelude
-2. Implement handlers in runtime
-3. Add effect-specific type checking rules
+1. Add generic effect support (`State<S>`)
+2. Implement `Fail` for error handling
+3. Add async/await pattern
 
 #### 2.3 Resumable Handlers
 **Status:** Handlers exist but may not support continuation resumption.
@@ -163,36 +204,51 @@ fn withRetry<E>(action: fn(): T with E, attempts: Int): T with E = ...
 ### Priority 4: Module System
 
 #### 4.1 Complete Import/Export
-**Status:** Basic imports work but incomplete.
+**Status:** ✅ Complete.
 
-**What's Missing:**
-- Re-exports
-- Module aliases working properly
-- Circular dependency detection (exists but needs testing)
-- Package/namespace management
+The module system is fully functional with:
+- `import foo/bar` - basic imports
+- `import foo/bar as alias` - aliased imports
+- `import foo.{a, b}` - selective imports
+- `import foo.*` - wildcard imports
+- `pub fn` visibility for exports
+- Circular dependency detection (tested)
+- Module caching
+- Transitive imports
+- Type checking across modules
 
-**Implementation Steps:**
-1. Implement proper module resolution
-2. Add re-export syntax
-3. Support qualified names everywhere
-4. Add package.lux for project configuration
+**Still Missing (nice-to-have):**
+- Re-exports (`pub import`)
+- Package manifest (`package.lux`)
 
 ### Priority 5: Code Generation
 
 #### 5.1 Compile to Target
-**Status:** Interpreter only.
+**Status:** ⚠️ Partial - JIT works for numeric code
 
-**Target Options:**
+**What's Working:**
+- `src/compiler.rs` - Cranelift JIT compiler (539 lines)
+- Integer arithmetic, comparisons, boolean ops
+- Conditionals, let bindings, function calls, blocks
+- Recursive functions (fib(30) compiles and runs)
+- CLI integration: `lux compile <file> [--benchmark]`
+- ~160x speedup over interpreter for numeric code
+
+**What's Missing in JIT:**
+- Strings, floats, lists, records, tuples
+- Pattern matching, ADTs
+- Effects and handlers
+
+**Target Options for Full Compilation:**
 1. **WASM** - Best for web and portable deployment
 2. **JavaScript** - Easiest web integration
-3. **LLVM IR** - Native performance
-4. **Custom bytecode** - VM-based execution
+3. **Extend Cranelift** - Build on existing JIT
 
 **Implementation Steps:**
-1. Design intermediate representation (IR)
-2. Implement IR generation from AST
-3. Implement backend for chosen target
-4. Add optimization passes
+1. ~~Expose JIT via CLI command~~ ✅ Done
+2. Add support for more types (strings, lists, etc.)
+3. Compile pattern matching
+4. Handle effects (CPS transform or evidence passing)
 
 ### Priority 6: Tooling
 
@@ -224,29 +280,36 @@ fn withRetry<E>(action: fn(): T with E, attempts: Int): T with E = ...
 ## Recommended Implementation Order
 
 ### Phase 1: Language Completeness (Essential)
-1. **Generic type parameters** - Required for proper List, Option, etc.
-2. **String interpolation** - Major usability improvement
-3. **Better error messages** - Critical for adoption
+1. ~~**Generic type parameters**~~ ✅ Done
+2. ~~**String interpolation**~~ ✅ Done
+3. **Better error messages** - Elm-quality suggestions
 
 ### Phase 2: Effect System Maturity
-4. **Built-in effects** (State, Fail, Reader)
-5. **Effect polymorphism**
-6. **Resumable handlers**
+4. ~~**Built-in effects** (Console, File, Http, Random, Time)~~ ✅ Done
+5. **Effect polymorphism** - Generic effect parameters
+6. **Fail effect** - Proper error handling pattern
+7. **Resumable handlers** - Multi-shot continuations
 
 ### Phase 3: Production Readiness
-7. **Complete module system**
-8. **Standard library**
-9. **Package manager**
+8. ~~**Complete module system**~~ ✅ Done
+9. ~~**Standard library basics**~~ ✅ Done (String, List, JSON)
+10. **Package manager** - Dependency resolution
+11. **Full compilation** - Extend JIT or add WASM/JS backend
 
-### Phase 4: Performance
-10. **Code generation** (WASM or JS first)
-11. **Optimization passes**
-12. **Incremental compilation**
+### Phase 4: Behavioral Types (Verification)
+12. **Total function verification** - Termination checking
+13. **Idempotent verification** - Pattern-based analysis
+14. **Where clause enforcement** - Constraint checking
 
-### Phase 5: Advanced Features
-13. **Schema evolution**
-14. **Refinement types**
-15. **SMT solver integration**
+### Phase 5: Schema Evolution (Data)
+15. **Type system version tracking**
+16. **Auto-migration generation**
+17. **Version-aware serialization**
+
+### Phase 6: Advanced Features
+18. **Refinement types** - SMT solver integration
+19. **Async/await effect**
+20. **Stream processing**
 
 ---
 
@@ -276,12 +339,15 @@ fn withRetry<E>(action: fn(): T with E, attempts: Int): T with E = ...
 | Type Inference | ✅ | ✅ | ✅ | Partial | Partial |
 | ADTs | ✅ | ✅ | ✅ | ✅ | Via unions |
 | Pattern Matching | ✅ | ✅ | ✅ | ✅ | Limited |
-| Generics | Partial | ✅ | ✅ | ✅ | ✅ |
+| Generics | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Type Classes | Basic | ✅ | ✅ | ✅ | ❌ |
+| String Interpolation | ✅ | ✅ | ❌ | ❌ | ✅ |
 | Effect Polymorphism | ❌ | ✅ | Via mtl | N/A | N/A |
-| Schema Evolution | Planned | ❌ | ❌ | ❌ | ❌ |
+| Schema Evolution | ⚠️ Parsing | ❌ | ❌ | ❌ | ❌ |
+| Behavioral Types | ⚠️ Parsing | ❌ | ❌ | ❌ | ❌ |
 | Refinement Types | Planned | ❌ | Via LH | ❌ | ❌ |
 | Tail Call Opt | ✅ | ✅ | ✅ | Limited | ❌ |
+| JIT Compilation | ⚠️ Numeric | ✅ | ✅ | N/A | N/A |
 | REPL | ✅ | ✅ | ✅ | Limited | ✅ |
 | LSP | Basic | ✅ | ✅ | ✅ | ✅ |