Documentation map

The top-level README is the product overview and quick start. This page routes readers to the durable references under doc/.

Documentation has three status levels:

• Files directly under doc/ describe implemented behavior and maintained interfaces.
• plan/ describes forward-looking work. A plan is not a release claim.
• ideas/ holds speculative designs that are not commitments.

kit --help, kit help COMMAND, and kit targets are the authoritative description of the commands and target profiles compiled into a particular binary.

Start here

Goal	Read
Understand the motivation and overall shape	Introducing kit
Understand the architecture and subsystem boundaries	Design
Use the command-line tools	Driver, then kit help COMMAND
Inspect targets and provisioning	Portability, then kit targets
Embed libkit.a	Embedding libkit, Interfaces
Package, authenticate, and install artifacts	Code distribution, Release/update
Define content-addressed builds	Build coordinator
Build and test kit itself	Build, Testing
Measure performance or component size	Benchmarking, Code size

Compiler and language pipeline

• Frontends describes frontend registration and the C, cpp, Wasm/WAT, and internal Toy frontends.
• Code generation describes the public KitCg API and the direct versus recorded lowering paths.
• IR defines the recorded semantic IR.
• Optimizer distinguishes the current no-SSA -O1 pipeline from the maintained but not-yet-enabled SSA -O2 schedule.
• Architecture backends covers target dispatch, native backends, instruction emission, and ABI seams.
• Assembler covers standalone and inline assembly.
• Grammar generator covers the EBNF compiler and generated lexer/parser runtimes.
• Portable C backend and WebAssembly cover the source-like output backends.
• Interpreter covers run --no-jit.

Objects, linking, execution, and debugging

• Object model covers ELF, Mach-O, COFF/PE, and Wasm objects behind the format-neutral builder and reader APIs.
• Linker covers resolution, layout, relocation, linker scripts, and JIT image creation.
• JIT covers executable-memory publication and symbol lookup.
• DWARF, Debugger, and Kernel/image support cover debug information, interactive execution, and freestanding images.
• Emulator documents the guest-ELF API and development command. The command is not part of the public inventory.

Runtime, hosts, and portability

• Runtime describes the freestanding headers and support library.
• OS interfaces inventories the public and internal boundaries through which hosts, frontends, and backends interact.
• Portability owns the cross/self-host test matrix and provisioning substrates; the public target registry owns target identity and capability.
• Windows records Windows-specific hosting and self-host details.

Project maintenance

• Build covers make products, component gates, reproducibility, and the three-stage fixed-point bootstrap.
• Testing is the test-suite and harness reference.
• Benchmarking defines reproducible compile-speed and generated-code-size measurements.
• Release/update documents versioning, signed artifacts, channel indexes, installation, rollback, and key rotation.

The historical black-box release audit is retained as evidence, not as current product documentation. Its baseline findings must not be used as descriptions of the current binary.