Update README.md and CLAUDE.md

Author: tomzx

CLAUDE.md

@@ -52,13 +52,29 @@ Code LoD is a CLI tool that generates and manages code descriptions at different
 
 ```
 src/code_lod/
-├── cli.py              # Main Typer CLI commands
-├── config.py           # Config/Paths management
+├── cli/                # Typer CLI commands (one file per command)
+│   ├── __init__.py     # Main app entry point
+│   ├── clean.py        # Clean all code-lod data
+│   ├── config.py       # Configuration management
+│   ├── generate.py     # Generate descriptions
+│   ├── hooks.py        # Git hooks installation
+│   ├── init.py         # Initialize code-lod
+│   ├── read.py         # Output descriptions
+│   ├── status.py       # Check freshness status
+│   ├── update.py       # Update stale descriptions
+│   └── validate.py     # Validate descriptions
+├── config.py           # Paths management
 ├── db.py               # SQLite hash index
 ├── hashing.py          # AST hash computation
 ├── models.py           # Pydantic data models
 ├── staleness.py        # StalenessTracker
-├── llm/                # LLM generator abstraction
+├── llm/
+│   ├── __init__.py
+│   └── description_generator/  # LLM generator abstraction
+│       ├── generator.py  # BaseGenerator interface
+│       ├── anthropic.py  # Anthropic Claude provider
+│       ├── openai.py     # OpenAI provider
+│       └── mock.py       # Mock generator for testing
 ├── parsers/            # BaseParser, tree-sitter implementations
 └── lod_file/           # .lod file read/write/comment parsing
 ```

README.md

@@ -75,6 +75,16 @@ Reading a project's README and source code works for small projects, but becomes
 
 ## Architecture
 
+Code LoD generates, manages, and updates code descriptions through a multi-layered pipeline:
+
+1. **Parsing** (`parsers/`): Tree-sitter based parsers extract code entities (functions, classes, modules) with AST hashes
+2. **Hashing** (`hashing.py`): AST hashes are computed on normalized source to detect semantic changes
+3. **Staleness Tracking** (`staleness.py`): Uses the hash index to determine if descriptions need regeneration
+4. **Generation** (`llm/description_generator/`): Abstract `BaseGenerator` interface for LLM providers (Anthropic, OpenAI, Mock)
+5. **Storage** (`db.py`, `lod_file/`): Dual storage system with SQLite database and `.lod` files
+
+### Storage
+
 Code LoD uses a dual storage system:
 
 1. **SQLite database** (`hash_index.db`) - Stores metadata, hashes, and descriptions with staleness tracking (should not be version controlled)