docs: Update documentation to reflect current codebase state

- solution-contract.md: Fix outdated parsing example (split -> json.loads)
- architecture/README.md: Correct package paths (packages/ -> src/)
- packages-overview.md: Correct directory scope (packages/ -> src/)
- runner/README.md: Fix Python version requirement (3.10+ -> 3.11)
- testing.md: Update pytest markers to reflect actual usage
- codegen/README.md: Add missing modules (tiered_solve_generator,
  problem_support, catalog/) and tiered solve_mode option

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

Author: lufftw

docs/architecture/README.md

@@ -36,9 +36,9 @@ The project follows a clean dependency hierarchy:
 | Module | Location | Role | Documentation |
 |--------|----------|------|---------------|
 | **runner** | `runner/` | Test execution engine | [Runner Spec](../runner/README.md) |
-| **codegen** | `packages/codegen/` | Solution skeleton generator | [CodeGen Spec](../packages/codegen/README.md) |
-| **leetcode_datasource** | `packages/leetcode_datasource/` | LeetCode data layer | [DataSource Spec](../packages/leetcode_datasource/README.md) |
-| **practice_workspace** | `packages/practice_workspace/` | Practice file management | [Workspace Spec](../packages/practice_workspace/README.md) |
+| **codegen** | `src/codegen/` | Solution skeleton generator | [CodeGen Spec](../packages/codegen/README.md) |
+| **leetcode_datasource** | `src/leetcode_datasource/` | LeetCode data layer | [DataSource Spec](../packages/leetcode_datasource/README.md) |
+| **practice_workspace** | `src/practice_workspace/` | Practice file management | [Workspace Spec](../packages/practice_workspace/README.md) |
 
 ## Design Principles
 

docs/architecture/packages-overview.md

@@ -1,17 +1,16 @@
 # Packages Architecture Overview
 
-> **Status**: Canonical Reference  
-> **Scope**: `packages/` directory architecture
+> **Status**: Canonical Reference
+> **Scope**: `src/` directory architecture
 
-This document provides an overview of the `packages/` directory structure and the relationships between packages.
+This document provides an overview of the `src/` directory structure and the relationships between packages.
 
 ---
 
 ## Directory Structure
 
 ```
-packages/
-├── __init__.py
+src/
 ├── codegen/                    # Solution skeleton generator (Stateless)
 │   ├── core/                   # Shared core components
 │   ├── reference/              # Reference skeleton generation

docs/contracts/solution-contract.md

@@ -77,13 +77,14 @@ class Solution:
 
 def solve():
     import sys
+    import json
     lines = sys.stdin.read().strip().split('\n')
-    nums = list(map(int, lines[0].split(',')))
+    nums = json.loads(lines[0])
     target = int(lines[1])
-    
+
     solver = get_solver(SOLUTIONS)
     result = solver.twoSum(nums, target)
-    print(result)
+    print(json.dumps(result, separators=(',', ':')))
 
 if __name__ == "__main__":
     solve()

docs/contributors/testing.md

@@ -218,13 +218,12 @@ Test results must be deterministic, unaffected by time, environment, or other fa
 ## Test Markers
 
 ```python
-@pytest.mark.unit          # Unit tests
 @pytest.mark.integration   # Integration tests
 @pytest.mark.edge_case     # Edge case tests
-@pytest.mark.slow          # Slow tests
-@pytest.mark.requires_big_o # Requires big-O package
 ```
 
+> **Note:** Currently only `integration` and `edge_case` markers are actively used in the test suite. The `edge_case` marker is defined in `pytest.ini`.
+
 ---
 
 ## Test Directory Structure

docs/packages/codegen/README.md

@@ -142,7 +142,7 @@ python -m codegen new <problem_id> --dry-run
 | Flag | Description |
 |------|-------------|
 | `--with-tests` | Generate `.in`/`.out` files from LeetCode examples |
-| `--solve-mode` | `placeholder` (default) or `infer` (auto-generate) |
+| `--solve-mode` | `placeholder` (default), `infer` (auto-generate), or `tiered` (for Tier-1/1.5 problems) |
 | `--force` | Overwrite existing test files |
 | `--dry-run` | Preview without writing files |
 | `--header-level` | `minimal`, `standard`, or `full` |
@@ -417,7 +417,7 @@ Total files: 218
 |---------|---------|-------------|
 | `header.level` | `"full"` | Header detail: `minimal`, `standard`, `full` |
 | `helpers.mode` | `"inline"` | Helper emit: `inline`, `import`, `none` |
-| `skeleton.solve_mode` | `"placeholder"` | solve() mode: `placeholder`, `infer` |
+| `skeleton.solve_mode` | `"placeholder"` | solve() mode: `placeholder`, `infer`, `tiered` |
 | `practice.multi_solution_mode` | `"single"` | Practice mode: `single`, `all` |
 
 ### Priority Order
@@ -543,7 +543,11 @@ codegen/
 │   ├── io_schema.py         # IO format inference
 │   ├── example_parser.py    # HTML example extraction
 │   ├── solve_generator.py   # solve() auto-generation
+│   ├── tiered_solve_generator.py  # Tiered solve() for Tier-1/1.5 problems
+│   ├── problem_support.py   # Problem-specific config loading
 │   ├── test_generator.py    # Test file generation
+│   ├── catalog/             # Problem catalog utilities
+│   │   └── __init__.py
 │   └── helpers/
 │       ├── __init__.py
 │       ├── catalog.py       # Canonical helper definitions
@@ -557,3 +561,13 @@ codegen/
     ├── generator.py         # Practice skeleton generation
     └── reuse.py             # Reuse from reference
 ```
+
+### Tiered Solve Generation
+
+For problems involving complex types (TreeNode, ListNode), use `--solve-mode tiered`:
+
+```bash
+python -m codegen new 104 --solve-mode tiered
+```
+
+This generates solve() functions with codec support for serialization/deserialization of complex types. See [Problem Support Boundary](../../contracts/problem-support-boundary.md) for tier definitions.

docs/runner/README.md

@@ -416,7 +416,7 @@ python runner/test_runner.py 0023 --all --benchmark
 
 ### Required
 
-- Python 3.10+
+- Python 3.11 (matching LeetCode official environment)
 - Solution files in `solutions/`
 - Test files in `tests/` (or use generators)