Reference map

Z is pre-alpha, so its documentation separates three questions that are easy to conflate:

1. What does accepted Z source mean?
2. Which accepted shapes do the current compiler tiers execute?
3. Why was the language designed this way, and what remains unsettled?

Use the source that matches the question.

Language semantics

The repository’s language reference is the current authoritative summary of accepted source semantics. It covers declarations, types, ownership, control flow, errors, generics, tasks, threads, native interfaces, and compilation.

The website’s language guide explains the same model progressively. When guide prose and exact wording appear to differ, report the discrepancy—the reference should provide the precise answer and both should be kept synchronized.

Compiler coverage

The implementation status records tested behavior and temporary compiler boundaries.

Status terms are used consistently:

Status	Meaning
Implemented	Parsed, checked, lowered, and regression-tested for the stated surface
Partial	A useful executable tier exists with named limitations
Experimental	Implemented evidence exists, but the design or breadth may still change
Designed	The semantic direction is accepted but is not yet generally executable
Planned	A desired investigation or capability, not current behavior

The detailed bootstrap status tracks Stage-0 and fixed-point native compiler parity. It is intentionally more technical and transient than the language guide.

Focused references

Topic	Reference
Diagnostics and error codes	Diagnostics
Testing and test tiers	Testing
Async tasks and cancellation	Async model
Executor and thread placement	Executor placement
Native interop safety tiers	Interop model
.zd vocabulary and contracts	Z declarations
Exporting a C ABI from Z	C exports
Performance methodology and evidence	Performance
Real-program ownership findings	Ownership pressure

These repository documents will move into fully navigable website reference pages incrementally. Linking the maintained sources now avoids publishing a second stale copy during that migration.

The September 8 benchmark refresh includes separate compiler build-latency and release-runtime suites. The build matrix distinguishes fresh project caches, unchanged rebuilds, source/header changes, and profile switches; runtime results include raw samples and allocation counts. These are workload-specific measurements, not universal speed claims.

Design rationale

DESIGN.md records the language charter, rationale, accepted directions, and deliberately open design questions. It is not a substitute for the language reference: design notes may discuss future syntax and experiments that are not current Z behavior.

File and tool reference

Surface	Purpose
.zs	Z source module
.zd	Additive checked semantic contract for a foreign module
z.json	Project target, entry point, linkage, and build configuration
z check	Parse, type-check, and validate ownership
z emit	Inspect the generated C-family translation unit
z build	Build the configured native artifact
z run	Build and execute a program
z test	Discover and run reachable inline Z tests
z metadata	Produce versioned checked metadata for tools and generators

During bootstrap, the Stage-0 forms are invoked through bun run z; the bootstrapped native executable uses the same command surface directly.