docs: document the source-to-binary compiler pipeline

[xodn348]

What

Adds a How It Works: Source to Binary section to the README, tracing 출력(1 + 2 * 3) through every stage of the toolchain:

source text → lexer → tokens → parser → AST → type checker → validated AST → codegen → LLVM IR → clang → binary

with a table of what each stage transforms and what it reports, and the interpreter branch shown alongside the compiled one.

Why

The README described the pipeline only in passing (hgl build (LLVM IR → clang → binary)). Anyone evaluating the project had no single place showing the stage boundaries or where the type checker sits.

The new Where LLVM fits subsection also separates two things that are routinely conflated:

1. cargo build hands Han's Rust source to rustc, which uses LLVM to produce the hgl binary.
2. hgl build hands the user's .hgl source through Han's own four stages into LLVM IR, and clang produces the user's binary.

Same back end, two unrelated levels. LLVM is a code generation library, not a runtime.

Also

docs/src/internals/architecture.md had drifted from the tree:

• the pipeline diagram omitted the type checker entirely
• the module list referenced interpreter.rs and codegen.rs, which are directories now
• typechecker.rs and builtins/ were missing

Fixed, since the new README section links here and would otherwise contradict it.

Verification

Docs only, no code touched. Every path and module name in the new text was checked against the working tree, and every claim against source: run_pipeline in src/main.rs confirms lexer → parser → typechecker ordering and that both back ends share it; typechecker::check returning Vec<TypeError> confirms type problems are collected rather than fatal; src/parser.rs confirms precedence climbing; compile_to_binary confirms IR is written as text and passed to clang.

🤖 Generated with Claude Code