docs: update README files with accurate codebase state

Fix stale/inaccurate information across 10 README files:
- Root: fill in Quick Example, fix .NET version, fix broken doc links,
  update project structure
- src/: rewrite compiler/core directory trees with actual file counts
- CLI: fix net9.0→net10.0, add --incremental option, fix invalid code
- CodeGen: add 3 missing partial files, complete type mapping table
- Validation: add 7 missing validators with Order values
- Services: add 5 missing files
- Project: document 7 partial files, add incremental compilation section
- TestFixtures: document .warning and .expected.cs test types
- Instructions: fix TypeChecker (5→8) and RoslynEmitter (8→11) counts
- Model: update incremental compilation from "future" to "implemented"

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

Author: antonsynd

.github/instructions/README.md

@@ -43,9 +43,9 @@ Lexer → Parser → Semantic → Validation → CodeGen → Tests
 
 1. **Lexer** (`Lexer/`) — Add `TokenType` and recognition
 2. **Parser** (`Parser/Ast/`) — Add AST record, parsing rule (6 partial files)
-3. **Semantic** (`Semantic/`) — Add type checking in `TypeChecker*.cs` (5 partial files)
+3. **Semantic** (`Semantic/`) — Add type checking in `TypeChecker*.cs` (8 partial files)
 4. **Validation** (`Semantic/Validation/`) — Add validator if needed (pluggable pipeline)
-5. **CodeGen** (`CodeGen/RoslynEmitter*.cs`) — Emit via `SyntaxFactory` (8 partial files)
+5. **CodeGen** (`CodeGen/RoslynEmitter*.cs`) — Emit via `SyntaxFactory` (11 partial files)
 6. **Tests** — Unit tests per component + `.spy`/`.expected` file-based tests
 
 ## Key Directories

README.md

@@ -9,11 +9,24 @@ Sharpy combines Python's elegant syntax with .NET's type safety and performance.
 
 ### Key Features
 
-🐍 **Pythonic Syntax** · ⚡ **Static Typing** · 🔗 **.NET Interop** · 🎯 **Null Safety** (`?.`, `??`) · 📦 **Zero Runtime Overhead**
+**Pythonic Syntax** | **Static Typing** | **.NET Interop** | **Null Safety** (`?.`, `??`) | **Zero Runtime Overhead**
 
 ## Quick Example
 
-TODO
+```python
+# hello.spy
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+def main():
+    message = greet("World")
+    print(message)
+```
+
+```bash
+$ dotnet run --project src/Sharpy.Cli -- run hello.spy
+Hello, World!
+```
 
 ## Language Highlights
 
@@ -56,7 +69,7 @@ def use_dotnet() -> None:
 
 ### Prerequisites
 
-- .NET 9.0 or .NET 10.0 SDK ([Download](https://dotnet.microsoft.com/download))
+- .NET 10.0 SDK ([Download](https://dotnet.microsoft.com/download))
 
 ### Build & Test
 
@@ -90,10 +103,7 @@ def main():
 
 ## Documentation
 
-- [Language Reference](docs/specs/language_reference.md) — Complete language specification
-- [Type System](docs/specs/type_system.md) — Type system details
-- [Manual](docs/manual/) — Variables, functions, types, control flow, errors
-- [Feature Support](docs/status/feature_support.md) — Implementation status
+- [Language Specification](docs/language_specification/) — Complete language reference
 
 ## Design Philosophy
 
@@ -111,13 +121,13 @@ Check our [issues](https://github.com/antonsynd/sharpy/issues) to get started.
 ```
 sharpy/
 ├── src/
-│   ├── Sharpy.Core/           # Standard library
+│   ├── Sharpy.Core/           # Standard library (runtime)
 │   ├── Sharpy.Compiler/       # Compiler (lexer, parser, semantic, codegen)
-│   ├── Sharpy.Cli/            # CLI tool
+│   ├── Sharpy.Cli/            # CLI tool (sharpyc)
 │   └── *.Tests/               # Test projects
-├── docs/                      # Documentation
-├── snippets/                  # Example programs
-└── lsp/sharpy/               # VS Code extension
+├── docs/language_specification/ # Language specification
+├── build_tools/               # Build automation and dogfooding tools
+└── snippets/                  # Example programs
 ```
 
 ## License

src/README.md

@@ -17,20 +17,44 @@ Sharpy.Compiler/
 │   │   ├── Node.cs     # Base AST node types
 │   │   ├── Statement.cs # Statement nodes
 │   │   ├── Expression.cs # Expression nodes
-│   │   └── Types.cs    # Type annotations
-│   └── Parser.cs       # Recursive descent parser
+│   │   ├── Types.cs    # Type annotations
+│   │   ├── Pattern.cs  # Pattern matching nodes
+│   │   └── ...         # Visitors, validators, future nodes
+│   ├── Parser.cs       # Recursive descent parser (6 partial files)
+│   └── Parser.*.cs     # .Definitions, .Expressions, .Primaries, .Statements, .Types
 ├── Diagnostics/        # Unified error handling
 │   ├── DiagnosticBag.cs # Structured diagnostic collection
 │   └── DiagnosticCodes.cs # SPY error code catalog
 ├── Semantic/           # Semantic analysis
 │   ├── Symbol.cs       # Symbol definitions
 │   ├── Scope.cs        # Scope management
 │   ├── SymbolTable.cs  # Symbol table
-│   └── BuiltinRegistry.cs # Builtin types/functions registry
-└── CodeGen/            # Code generation
-    ├── RoslynEmitter.cs # Generates C# using Roslyn
-    ├── NameMangler.cs   # Name conversion (snake_case → PascalCase)
-    └── CodeGenContext.cs # Code generation state
+│   ├── BuiltinRegistry.cs # Builtin types/functions registry
+│   ├── TypeChecker.cs  # Type checking (8 partial files)
+│   ├── TypeChecker.*.cs # .Definitions, .Expressions, .Expressions.Access,
+│   │                    # .Expressions.Literals, .Expressions.Operators,
+│   │                    # .Statements, .Utilities
+│   └── Validation/     # Pluggable validation pipeline (16 validators)
+├── CodeGen/            # Code generation
+│   ├── RoslynEmitter.cs # Generates C# using Roslyn (11 partial files)
+│   ├── RoslynEmitter.*.cs # .Expressions, .Expressions.Access, .Expressions.Literals,
+│   │                      # .Expressions.Operators, .Statements, .TypeDeclarations,
+│   │                      # .ClassMembers, .CompilationUnit, .ModuleClass, .Operators
+│   ├── TypeMapper.cs    # Maps Sharpy types to C# types
+│   ├── NameMangler.cs   # Name conversion (snake_case → PascalCase)
+│   ├── CodeGenContext.cs # Code generation state
+│   └── CodeValidator.cs # Validates generated code compiles
+├── Project/            # Multi-file project compilation
+│   ├── ProjectCompiler.cs # Orchestrates compilation (7 partial files)
+│   ├── SpyProject.cs     # Project file parsing
+│   ├── DependencyGraph.cs # Build ordering
+│   └── IncrementalCompilationCache.cs # Incremental compilation
+├── Services/           # Centralized compiler services layer
+├── Discovery/          # CLR type discovery
+├── Model/              # Core data model (CompilationUnit, ProjectModel)
+├── Analysis/           # Control flow graph infrastructure
+├── Shared/             # Constants, keyword escaping, type names
+└── Text/               # Source text, spans, locations
 ```
 
 ### Sharpy.Core
@@ -39,15 +63,24 @@ The runtime library that compiled Sharpy code depends on.
 ```
 Sharpy.Core/
 ├── Builtins/           # Always-available types and functions
-│   └── Exports.cs      # Global functions (print, len, etc.)
+│   ├── Builtins.cs     # Builtin function dispatch (partial class)
+│   └── Exceptions.cs   # Builtin exception types
 ├── Partial.List/       # List[T] implementation (partial class pattern)
 ├── Partial.Set/        # Set[T] implementation
-├── Partial.*/          # Other type implementations split by interface
+├── Partial.Complex/    # Complex number implementation
+├── Partial.Iterator/   # Iterator base implementation
+├── Partial.ListIterator/ # List iterator
+├── Partial.ListReverseIterator/ # Reverse list iterator
+├── Partial.SetIterator/ # Set iterator
 ├── Collections/        # Collection interfaces
 ├── Dict.cs             # dict[K,V] implementation
 ├── Range.cs            # range() builtin
 ├── Enumerate.cs        # enumerate() builtin
-└── *.cs                # Other builtins (Zip, Map, Filter, etc.)
+├── Print.cs            # print() builtin
+├── Len.cs              # len() builtin
+├── ISized.cs           # Protocol interface for len()
+├── IBoolConvertible.cs # Protocol interface for bool()
+└── *.cs                # Other builtins (Zip, Map, Filter, Sorted, etc.)
 ```
 
 ## Key Design Decisions
@@ -63,7 +96,7 @@ var methods = listType.GetMethods(); // Get all Sharpy list methods
 
 ### 2. Roslyn Code Generation
 Uses Microsoft.CodeAnalysis (Roslyn) to:
-- Generate C# syntax trees
+- Generate C# syntax trees via `SyntaxFactory` (no string templating)
 - Emit optimized IL directly
 - Produce PDB debug symbols
 - Leverage existing .NET optimizations

src/Sharpy.Cli/README.md

@@ -40,6 +40,7 @@ sharpyc emit csharp <input.spy>   # Generated C# code
 ### Project Options
 
 - `-c, --configuration <Debug|Release>` - Build configuration (default: Debug)
+- `--incremental` - Enable incremental compilation (skip unchanged files)
 - `--clean` - Delete bin/ and obj/ directories before building
 - `--emit-cs-to <dir>` - Save generated C# code to directory
 
@@ -123,12 +124,12 @@ Create a `.spyproj` file to define your multi-file Sharpy project:
 ```
 bin/
   Debug/
-    net9.0/
+    net10.0/
       MyApp.exe
       MyApp.dll
       MyApp.pdb
   Release/
-    net9.0/
+    net10.0/
       MyApp.exe
       MyApp.dll
 ```
@@ -178,8 +179,8 @@ def greet(name: str) -> None:
     message: str = f"Hello, {name}!"
     print(message)
 
-x = 42
-greet("World")
+def main():
+    greet("World")
 ```
 
 Run the compiler:

src/Sharpy.Compiler.Tests/Integration/TestFixtures/README.md

@@ -43,6 +43,30 @@ errors/
 └── undefined_var.error  # Contains: "undefined_var" (substring to match)
 ```
 
+### Warning Tests (compilation should succeed with expected warnings)
+
+1. Create a `.spy` file with Sharpy code that produces warnings
+2. Create a matching `.expected` file with the expected stdout output
+3. Create a matching `.warning` file:
+   - Empty `.warning` file means expect **no** warnings
+   - Non-empty lines are expected substrings that must appear in warnings
+
+Example:
+```
+warnings/
+├── unused_var.spy          # Code that triggers a warning
+├── unused_var.expected     # Expected stdout output
+└── unused_var.warning      # Contains: "unused variable" (substring to match)
+```
+
+### C# Snapshot Tests (verify generated C# output)
+
+1. Create a `.spy` file and a matching `.expected.cs` file with the expected generated C#
+2. The expected C# is Roslyn-normalized
+3. To regenerate snapshots: `UPDATE_SNAPSHOTS=true dotnet test --filter "FullyQualifiedName~FileBasedIntegrationTests"`
+
+Used selectively for representative fixtures to detect codegen changes that don't affect runtime output.
+
 ### Skipping Tests
 
 To temporarily skip a test that is pending a fix:

src/Sharpy.Compiler/CodeGen/README.md

@@ -4,15 +4,18 @@ This directory contains the Roslyn-based C# code generator.
 
 ## Key Files
 
-- `RoslynEmitter.cs` - Main emitter, orchestrates code generation
-- `RoslynEmitter.*.cs` - Partial classes for different AST node types:
+- `RoslynEmitter.cs` - Main emitter, orchestrates code generation and name resolution
+- `RoslynEmitter.*.cs` - Partial classes for different AST node types (11 files total):
   - `.Expressions.cs` - Expression generation
+  - `.Expressions.Access.cs` - Member access, indexing, slicing
+  - `.Expressions.Literals.cs` - Literal expressions (numbers, strings, collections)
+  - `.Expressions.Operators.cs` - Binary/unary operator expressions
   - `.Statements.cs` - Statement generation
   - `.TypeDeclarations.cs` - Class/struct/interface/enum generation
   - `.ClassMembers.cs` - Methods, properties, constructors
   - `.ModuleClass.cs` - Module class generation (named after source file)
   - `.CompilationUnit.cs` - Top-level compilation unit
-  - `.Operators.cs` - Binary/unary operators
+  - `.Operators.cs` - Operator method emission
 - `CodeGenContext.cs` - Shared context for emission
 - `TypeMapper.cs` - Maps Sharpy types to C# types
 - `NameMangler.cs` - Converts snake_case to PascalCase, dunder methods
@@ -136,13 +139,16 @@ Local variables still require tracking during emission for redeclaration handlin
 
 `TypeMapper` handles the translation from Sharpy types to C# types:
 
-- `list[T]` → `global::Sharpy.List<T>`
-- `dict[K, V]` → `global::Sharpy.Dict<K, V>`
-- `str` → `string`
 - `int` → `int`
 - `long` → `long`
 - `float` → `double`
+- `double` → `double`
+- `float32` → `float`
+- `str` → `string`
 - `bool` → `bool`
+- `list[T]` → `global::Sharpy.List<T>`
+- `dict[K, V]` → `global::Sharpy.Dict<K, V>`
+- `set[T]` → `global::Sharpy.Set<T>`
 - `None` → `void`
 
 ## Name Mangling

src/Sharpy.Compiler/Model/README.md

@@ -55,8 +55,8 @@ var errors = unit.Diagnostics.GetAll();
 2. **Thread-safety**: DiagnosticBag is thread-safe for future parallel
    compilation support.
 
-3. **Incremental compilation ready**: Content hashing and dependency
-   tracking support future incremental compilation.
+3. **Incremental compilation**: Content hashing and dependency
+   tracking enable incremental compilation (skip unchanged files).
 
 4. **LSP ready**: Token storage and source spans enable future IDE
    integration.

src/Sharpy.Compiler/Project/README.md

@@ -4,10 +4,12 @@ This directory contains components for multi-file project compilation.
 
 ## Key Files
 
-- `ProjectCompiler.cs` - Orchestrates multi-file compilation pipeline
+- `ProjectCompiler.cs` - Orchestrates multi-file compilation pipeline (7 partial files):
+  - `.cs` (main), `.Initialization.cs`, `.Parsing.cs`, `.Phases.cs`, `.CodeGen.cs`, `.IncrementalCache.cs`, `.Utilities.cs`
 - `SpyProject.cs` - Project configuration and file discovery
 - `DependencyGraph.cs` - Immutable dependency graph for build ordering
 - `DependencyGraphBuilder.cs` - Thread-safe builder for dependency graph
+- `IncrementalCompilationCache.cs` - File hash and symbol caching for incremental builds
 
 ## ProjectCompiler
 
@@ -68,6 +70,16 @@ Handles project file parsing and source file discovery:
 - Resolves package dependencies
 - Configures compilation options
 
+## Incremental Compilation
+
+Enable with `--incremental` to skip unchanged files:
+
+1. **First build**: All files compiled, symbols and C# cached to `obj/{Config}/.sharpy-symbols`
+2. **Subsequent builds**: Files skipped if content hash matches and dependencies unchanged
+3. **Transitive deps**: If file A imports B and B changes, A is recompiled
+
+Cache is auto-invalidated on compiler version or schema version changes.
+
 ## Design Notes
 
 - `DependencyGraph` is immutable for thread safety

src/Sharpy.Compiler/Semantic/Validation/README.md

@@ -16,16 +16,23 @@ of semantic rules.
 - `SemanticContext.cs` - Shared context passed to validators
 - `AstTraversalContext.cs` - Tracks traversal state
 
-### Validators
-
-- `ModuleLevelValidator.cs` - Entry point rules, module-level type annotations
-- `DecoratorValidator.cs` - Decorator usage validation
-- `SignatureValidator.cs` - Function/method signature checks (dunders, protocols)
-- `DefaultParameterValidator.cs` - Default parameter constraints
-- `ControlFlowValidator.cs` - CFG-based control flow analysis
-- `AccessValidator.cs` - Member access validation
-- `ProtocolValidator.cs` - Protocol method validation (__len__, __iter__, etc.)
-- `OperatorValidator.cs` - Binary/unary operator type checking
+### Validators (ordered by execution priority)
+
+- `ModuleLevelValidator.cs` (Order 50) - Entry point rules, module-level type annotations
+- `NamingConventionValidator.cs` (Order 55) - Naming convention checks
+- `DecoratorValidator.cs` (Order 60) - Decorator usage validation
+- `SignatureValidator.cs` (Order 150) - Dunder method signatures, protocol conformance
+- `EqualityContractValidator.cs` (Order 160) - Equality contract checks (__eq__/__hash__)
+- `InterfaceConflictValidator.cs` (Order 170) - Interface conflict detection
+- `DefaultParameterValidator.cs` (Order 250) - Default parameter constraints
+- `ControlFlowValidator.cs` (Order 400) - CFG-based control flow analysis
+- `PropertyValidator.cs` (Order 410) - Property validation
+- `UnusedVariableValidator.cs` (Order 420) - Unused variable warnings
+- `UnusedImportValidator.cs` (Order 430) - Unused import warnings
+- `AccessValidator.cs` (Order 450) - Private/protected member access validation
+- `DunderInvocationValidator.cs` (Order 460) - Direct dunder call warnings
+- `ProtocolValidator.cs` (Order 500) - Protocol method validation (__len__, __iter__, etc.)
+- `OperatorValidator.cs` (Order 500) - Unsupported operator type checking
 
 ## Architecture
 
@@ -53,7 +60,7 @@ operate as a self-contained AST analysis.
 
 ### TypeChecker (type-inference-coupled)
 
-These validations live in `TypeChecker` because they are tightly coupled to the
+These validations live in `TypeChecker` (8 partial files) because they are tightly coupled to the
 type inference walk and depend on in-progress type resolution state:
 
 - **Type mismatches** — assignment/return type compatibility (SPY0220, SPY0221)

src/Sharpy.Compiler/Services/README.md

@@ -19,17 +19,29 @@ The services layer provides common operations used throughout compilation:
 
 ## Files
 
+### Core
+- `CompilerServices.cs` - Main service container
+- `CompilerServicesBuilder.cs` - Builder for constructing services
+- `CompilerServicesConfiguration.cs` - Immutable configuration
+
+### Interfaces
 - `ITypeResolver.cs` - Type resolution service interface
 - `ISymbolLookup.cs` - Symbol lookup service interface
 - `IClrTypeMapper.cs` - CLR type mapping service interface
 - `IDiagnosticReporter.cs` - Diagnostic reporting service interface
+- `IDependencyQuery.cs` - Dependency graph query interface
+- `IImportQuery.cs` - Import resolution query interface
+- `ISemanticQuery.cs` - Semantic information query interface
+
+### Adapters
 - `TypeResolverAdapter.cs` - Adapter wrapping existing TypeResolver
 - `SymbolLookupAdapter.cs` - Adapter wrapping existing SymbolTable
 - `ClrTypeMapperAdapter.cs` - Adapter for CLR type mapping
+- `ImportQueryAdapter.cs` - Adapter for import queries
 - `DiagnosticReporter.cs` - Implementation of diagnostic reporting
-- `CompilerServicesConfiguration.cs` - Immutable configuration
-- `CompilerServices.cs` - Main service container
-- `CompilerServicesBuilder.cs` - Builder for constructing services
+
+### Utilities
+- `AstPositionService.cs` - AST position lookup utilities
 
 ## Usage