Update documentation to reflect current implementation state

README now documents all 70+ implemented words, working examples,
architecture overview, and accurate compliance status.
CLAUDE.md updated with actual file descriptions, patterns for adding
new words, and current test count.

README.md

@@ -4,24 +4,51 @@
 
 An optimizing Forth 2012 compiler targeting WebAssembly.
 
+## Status
+
+WAFER is a working Forth system. It JIT-compiles each word definition to a separate WASM module and executes via `wasmtime`. 185 tests passing.
+
+**Working features:**
+- Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
+- 70+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system
+- Recursion (RECURSE), nested control structures, loop counters (I, J)
+- VARIABLE, CONSTANT, CREATE
+- Number bases (HEX, DECIMAL), number prefixes ($hex, #dec, %bin)
+- Comments (backslash, parentheses), string output (." ...)
+- Interactive REPL with line editing
+
+**Example session:**
+```forth
+: FIB DUP 2 < IF DROP 1 ELSE DUP 1 - RECURSE SWAP 2 - RECURSE + THEN ;
+: FIBS 0 DO I FIB . LOOP ;
+12 FIBS CR    \ prints: 1 1 2 3 5 8 13 21 34 55 89 144
+
+VARIABLE COUNTER  0 COUNTER !
+: BUMP COUNTER @ 1 + COUNTER ! ;
+BUMP BUMP BUMP COUNTER @ .  \ prints: 3
+```
+
 ## Goals
 
 - **Full Forth 2012 compliance** -- all word sets, 100% test suite pass rate
 - **Optimizing compiler** -- constant folding, inlining, peephole optimization, stack-to-local promotion
-- **Multi-typed stack** -- type inference uses WASM's native typed stack when possible, memory fallback for dynamic cases
-- **Self-hosting** -- minimal Rust kernel (~35 primitives), everything else written in WAFER Forth
-- **Dual mode** -- JIT for interactive development, consolidation recompilation into a single optimized WASM module
+- **Multi-typed stack** -- type inference uses WASM's native typed stack when possible
+- **Self-hosting** -- minimal Rust kernel (~35 primitives), everything else in WAFER Forth
+- **Consolidation mode** -- recompile all JIT words into a single optimized WASM module
 
 ## Architecture
 
 ```
-Forth Source -> Outer Interpreter -> IR (with type inference) -> Optimization -> WASM Codegen
+Forth Source -> Outer Interpreter -> IR -> [Optimize] -> WASM Codegen (wasm-encoder)
+                                                              |
+                                                    wasmtime instantiation
+                                                    (shared memory + table)
 ```
 
-- **Subroutine threading** via WASM function tables
-- **JIT mode**: each new word compiles to a separate WASM module
-- **Consolidation mode**: recompile all words into a single module with direct calls
-- **IR-based pipeline** enables optimization passes before WASM emission
+- **Subroutine threading** via WASM function tables and `call_indirect`
+- **JIT mode**: each new word compiles to a separate WASM module linked to shared memory/globals/table
+- **IR-based pipeline** enables future optimization passes before WASM emission
+- **Dictionary**: linked-list word headers in simulated linear memory
 
 ## Building
 
@@ -38,43 +65,62 @@ cargo run -p wafer
 # Run a Forth file
 cargo run -p wafer -- file.fth
 
-# Compile to optimized WASM
-cargo run -p wafer -- --consolidate file.fth -o output.wasm
+# Pipe input
+echo ': SQUARE DUP * ; 7 SQUARE .' | cargo run -p wafer
 ```
 
 ## Testing
 
 ```bash
-# All tests
+# All tests (185 currently passing)
 cargo test --workspace
 
 # Forth 2012 compliance dashboard
-cargo test --test compliance
+cargo test -p wafer-core --test compliance
 
-# Benchmarks
-cargo bench --workspace
+# Lints
+cargo clippy --workspace
 ```
 
 ## Project Structure
 
 ```
 crates/
-  core/       wafer-core: compiler, IR, optimizer, codegen
-  cli/        wafer: CLI REPL and AOT compiler
+  core/       wafer-core: dictionary, IR, codegen (wasm-encoder), outer interpreter
+  cli/        wafer: CLI REPL and file execution (wasmtime, rustyline)
   web/        wafer-web: browser bindings (planned)
-forth/        Standard library written in WAFER Forth
-tests/        Integration tests and Forth 2012 compliance suite
+forth/        Standard library in WAFER Forth (planned, currently stubs)
+tests/        Forth 2012 compliance suite (gerryjackson/forth2012-test-suite submodule)
 ```
 
+## Implemented Words
+
+### Core (Forth 2012 Section 6.1) -- In Progress
+
+**Stack:** DUP DROP SWAP OVER ROT NIP TUCK 2DUP 2DROP 2SWAP 2OVER ?DUP PICK DEPTH
+**Arithmetic:** + - * / MOD /MOD NEGATE ABS MIN MAX 1+ 1- 2* 2/
+**Comparison:** = <> < > U< 0= 0< 0<> 0> WITHIN
+**Logic:** AND OR XOR INVERT LSHIFT RSHIFT
+**Memory:** @ ! C@ C! +! HERE ALLOT , C, CELLS CELL+ CHARS CHAR+ ALIGNED ALIGN MOVE FILL
+**Control (compile-time):** IF ELSE THEN DO LOOP +LOOP I J UNLOOP LEAVE BEGIN UNTIL WHILE REPEAT RECURSE EXIT
+**Defining:** : ; VARIABLE CONSTANT CREATE IMMEDIATE
+**I/O:** . .S CR EMIT SPACE SPACES TYPE ." S"
+**Return stack:** >R R> R@
+**System:** EXECUTE ' CHAR [CHAR] ['] DECIMAL HEX BASE >BODY ENVIRONMENT? SOURCE ABORT TRUE FALSE BL
+**Compiler:** LITERAL POSTPONE [ ]
+
+### Not Yet Implemented
+
+DOES> EVALUATE >NUMBER ACCEPT WORD FIND COUNT CMOVE CMOVE> >IN #TIB STATE (as variable) ABORT" and others needed for full Core compliance.
+
 ## Compliance Status
 
-Targeting 100% Forth 2012 compliance, tested with [Gerry Jackson's forth2012-test-suite](https://github.com/gerryjackson/forth2012-test-suite).
+Targeting 100% Forth 2012 compliance via [Gerry Jackson's test suite](https://github.com/gerryjackson/forth2012-test-suite).
 
 | Word Set | Status |
 |----------|--------|
-| Core | Pending |
+| Core | In progress (~70%) |
 | Core Extensions | Pending |
-| Block | N/A |
 | Double-Number | Pending |
 | Exception | Pending |
 | Facility | Pending |