# Zena docs — content outline

<!-- Generated by scripts/print-outline.js. Edit src/_data/sidebar.js. -->

This is the plan for the documentation site. The sidebar configuration in
[`src/_data/sidebar.js`](src/_data/sidebar.js) is the source of truth: it
defines the navigation, the page order, and — via each leaf's `outline` —
the sections a page is meant to cover.

To add a page: add it to the sidebar with an `outline`, then run
`node scripts/scaffold-docs.js` to create the stub.

**Status:** ✅ written · 📝 placeholder

## Guide

- **Introduction**
  - ✅ [What is Zena?](src/guide/what-is-zena.md) — `/guide/what-is-zena/`
    - A language shaped by its target
    - How it compares
    - What it looks like
    - Where the project stands
  - ✅ [Why Zena?](src/guide/why-zena.md) — `/guide/why-zena/`
    - The Wasm GC gap
    - Nothing in your module but your code
    - Compilation fast enough to stay in the loop
    - Correctness is where the field is going
    - Familiar to humans and to agents
    - Why WebAssembly at all
    - No users is a superpower
    - Where Zena fits
  - ✅ [Language Overview](src/guide/overview.md) — `/guide/overview/`
    - Values and variables
    - Functions
    - Types
    - Classes
    - Pattern matching
    - Collections
    - Errors
    - Libraries
    - Borrowed from other languages
  - ✅ [Getting Started](src/guide/getting-started.md) — `/guide/getting-started/`
    - Install the toolchain
    - Create a project
    - Build and run
    - Editor setup
    - Next steps
  - ✅ [Your First Program](src/guide/first-program.md) — `/guide/first-program/`
    - Hello, world
    - Adding a function
    - Types and inference
    - Reading input
    - Compiling to Wasm
- **Language Basics**
  - 📝 [Values and Variables](src/guide/values-and-variables.md) — `/guide/values-and-variables/`
    - let and var
    - Immutability by default
    - Type annotations and inference
    - Scoping and shadowing
  - 📝 [Types](src/guide/types.md) — `/guide/types/`
    - Everything has a type
    - Primitives and references
    - Nominal and structural types
    - Unions and what may go in them
    - Type aliases and distinct types
  - 📝 [Functions](src/guide/functions.md) — `/guide/functions/`
    - Arrow functions only
    - Parameters, defaults, and optionals
    - Closures and their cost
    - Contextual typing
    - Generic functions
  - 📝 [Control Flow and Matching](src/guide/control-flow.md) — `/guide/control-flow/`
    - Expression-oriented control flow
    - if, match, and exhaustiveness
    - Loops and iteration
    - if let and while let
  - 📝 [Collections](src/guide/collections.md) — `/guide/collections/`
    - FixedArray and Array
    - Maps and Sets
    - Iterating
    - Choosing a collection
  - 📝 [Classes and Objects](src/guide/classes.md) — `/guide/classes/`
    - Declaring a class
    - Constructors and initialization
    - Interfaces and mixins
    - Sealed hierarchies and case classes
    - Records versus classes
  - 📝 [Errors](src/guide/errors.md) — `/guide/errors/`
    - Throwing and catching
    - try as an expression
    - Errors versus result values
    - When to use which
  - 📝 [Libraries](src/guide/libraries.md) — `/guide/libraries/`
    - A library is a directory
    - Imports and exports
    - Using the standard library
    - Depending on other packages
- **Core Concepts**
  - 📝 [The Type System](src/guide/type-system.md) — `/guide/type-system/`
    - Goals
    - Assignability and subtyping
    - Narrowing
    - Variance
    - What Zena deliberately leaves out
  - 📝 [Correctness and Safety](src/guide/correctness.md) — `/guide/correctness/`
    - What "sound" means
    - Where TypeScript gives up soundness
    - What Zena does instead
    - Memory safety without a borrow checker
    - The cost of soundness
  - 📝 [WebAssembly](src/guide/web-assembly.md) — `/guide/web-assembly/`
    - Wasm GC in one page
    - How Zena values map to Wasm types
    - What is heap-allocated
    - Linear memory and when you need it
  - 📝 [Performance](src/guide/performance.md) — `/guide/performance/`
    - What each construct costs
    - Monomorphized generics
    - Devirtualization
    - Boxing and how to avoid it
    - What ends up in the binary
    - Dead code elimination
    - Measuring
  - 📝 [Strings and Unicode](src/guide/strings.md) — `/guide/strings/`
    - One String type, several representations
    - WTF-8 and WTF-16
    - Slices, views, and copies
    - Building and parsing strings
- **Building Things**
  - 📝 [Project Layout](src/guide/project-layout.md) — `/guide/project-layout/`
    - Anatomy of a project
    - The package manifest
    - Source and test directories
    - Build output
  - 📝 [Testing](src/guide/testing.md) — `/guide/testing/`
    - Writing a test
    - Assertions
    - Running tests
    - Benchmarks
  - 📝 [Editor Support](src/guide/editor-support.md) — `/guide/editor-support/`
    - VS Code
    - The language server
    - Other editors
  - 📝 [Formatting](src/guide/formatting.md) — `/guide/formatting/`
    - zena fmt
    - Style decisions
    - Editor integration
  - 📝 [Working with AI Agents](src/guide/ai-agents.md) — `/guide/ai-agents/`
    - Why Zena is designed for agent feedback loops
    - Diagnostics agents can act on
    - Tooling hooks
    - Practical tips
- **Coming From…**
  - 📝 [TypeScript](src/guide/from/typescript.md) — `/guide/from/typescript/`
    - What carries over
    - let means immutable
    - No implicit coercion, no any escape hatch
    - Nominal classes
    - Cheat sheet
  - 📝 [Rust](src/guide/from/rust.md) — `/guide/from/rust/`
    - GC instead of ownership
    - Matching and sealed classes
    - Traits versus interfaces and mixins
    - Cheat sheet
  - 📝 [Go](src/guide/from/go.md) — `/guide/from/go/`
    - Nominal interfaces
    - Errors
    - Generics
    - Concurrency, and what Zena has instead
    - Cheat sheet
  - 📝 [Swift and Dart](src/guide/from/swift-dart.md) — `/guide/from/swift-dart/`
    - Constructors and initializer lists
    - Mixins
    - Optionals and non-nullable references
    - Cheat sheet
  - 📝 [Java, Kotlin, and Scala](src/guide/from/jvm.md) — `/guide/from/jvm/`
    - Classes and sealed hierarchies
    - Case classes and pattern matching
    - Expression orientation
    - Cheat sheet
- **Targets and Interop**
  - 📝 [Compile Targets](src/guide/targets.md) — `/guide/targets/`
    - host
    - wasi
    - Choosing a target
    - Feature differences
  - 📝 [JavaScript Interop](src/guide/javascript-interop.md) — `/guide/javascript-interop/`
    - Loading a module
    - Passing values across the boundary
    - Strings and the host
    - Calling back into JavaScript
  - 📝 [WASI and Components](src/guide/wasi.md) — `/guide/wasi/`
    - Running under wasmtime
    - Capabilities
    - WIT imports and exports
    - The component model

## Reference

- **Overview**
  - ✅ [Introduction](src/reference/index.md) — `/reference/`
    - How to read this reference
    - Conventions
    - Feature status
  - ✅ [Quick Reference](src/reference/quick-reference.md) — `/reference/quick-reference/`
  - 📝 [Lexical Structure](src/reference/lexical-structure.md) — `/reference/lexical-structure/`
    - Source encoding
    - Comments
    - Identifiers
    - Keywords
    - Literals
    - Semicolons
  - 📝 [Program Structure](src/reference/program-structure.md) — `/reference/program-structure/`
    - Files and libraries
    - Top-level declarations
    - Entry points
    - Initialization order
- **Declarations**
  - 📝 [Variables](src/reference/variables.md) — `/reference/variables/`
    - let
    - var
    - Type annotations
    - Definite assignment
    - Shadowing
  - 📝 [Functions](src/reference/functions.md) — `/reference/functions/`
    - Function expressions
    - Parameters
    - Default and optional parameters
    - Arity adaptation
    - Return types
    - Closures
    - Top-level functions versus closures
    - Generic functions
  - 📝 [Type Aliases and Distinct Types](src/reference/type-aliases.md) — `/reference/type-aliases/`
    - type
    - distinct type
    - Generic aliases
    - Conversions
- **Types**
  - 📝 [Type System Overview](src/reference/types.md) — `/reference/types/`
    - The type hierarchy
    - Assignability
    - Nominal versus structural
    - any, anyref, and never
  - 📝 [Primitives](src/reference/primitives.md) — `/reference/primitives/`
    - Integers
    - Floats
    - boolean
    - Numeric conversions
    - Overflow and wrapping
    - Special float values
  - 📝 [Strings](src/reference/strings.md) — `/reference/strings/`
    - The String type
    - Literals and escapes
    - Indexing and slicing
    - Comparison and equality
    - Encodings
  - 📝 [Unions](src/reference/unions.md) — `/reference/unions/`
    - Declaring a union
    - What may appear in a union
    - Why primitives are restricted
    - Narrowing a union
    - Literal types
  - 📝 [Generics](src/reference/generics.md) — `/reference/generics/`
    - Type parameters
    - Constraints
    - Monomorphization
    - Variance
    - Inference
  - 📝 [Inference and Narrowing](src/reference/inference.md) — `/reference/inference/`
    - Local inference
    - Contextual typing
    - Control-flow narrowing
    - is and as
- **Expressions**
  - 📝 [Expressions](src/reference/expressions.md) — `/reference/expressions/`
    - Literals
    - Member access
    - Calls
    - Conditional expressions
    - Block expressions
    - Evaluation order
  - 📝 [Operators](src/reference/operators.md) — `/reference/operators/`
    - Arithmetic
    - Comparison and equality
    - Logical
    - Bitwise
    - Assignment and compound assignment
    - Type operators
  - 📝 [Operator Precedence](src/reference/operator-precedence.md) — `/reference/operator-precedence/`
    - Precedence table
    - Associativity
  - 📝 [Template Literals](src/reference/template-literals.md) — `/reference/template-literals/`
    - Interpolation
    - Multi-line strings
    - Tagged templates
  - 📝 [Ranges](src/reference/ranges.md) — `/reference/ranges/`
    - Range syntax
    - Iterating a range
    - Slicing with ranges
  - 📝 [Pipelines](src/reference/pipelines.md) — `/reference/pipelines/`
    - The pipeline operator
    - Placeholders
    - Status
- **Statements and Control Flow**
  - 📝 [Control Flow](src/reference/control-flow.md) — `/reference/control-flow/`
    - if
    - match
    - Blocks
    - return
    - throw
  - 📝 [Loops](src/reference/loops.md) — `/reference/loops/`
    - while
    - for
    - for-in
    - break and continue
    - Labels
    - while let
  - 📝 [Pattern Matching](src/reference/pattern-matching.md) — `/reference/pattern-matching/`
    - match expressions
    - Pattern forms
    - Guards
    - Or patterns
    - Exhaustiveness checking
    - if let
  - 📝 [Destructuring](src/reference/destructuring.md) — `/reference/destructuring/`
    - Record patterns
    - Tuple patterns
    - Class patterns
    - Rest and defaults
- **Data Types**
  - 📝 [Records](src/reference/records.md) — `/reference/records/`
    - Record literals
    - Record types
    - Spread
    - Structural typing
    - Representation
  - 📝 [Tuples](src/reference/tuples.md) — `/reference/tuples/`
    - Tuple literals
    - Inline tuples
    - Multi-value returns
    - Representation
  - 📝 [Arrays](src/reference/arrays.md) — `/reference/arrays/`
    - FixedArray
    - Array
    - ImmutableArray
    - Literals
    - Indexing and bounds
    - Slicing
  - 📝 [Maps and Sets](src/reference/maps.md) — `/reference/maps/`
    - Map
    - OrderedMap
    - Set
    - Keys, hashing, and equality
    - Literals
  - 📝 [Enums](src/reference/enums.md) — `/reference/enums/`
    - Declaring an enum
    - Backing types
    - Conversions
    - Enums versus sealed classes
  - 📝 [Boxing](src/reference/boxing.md) — `/reference/boxing/`
    - Box
    - Automatic boxing
    - Costs
- **Classes**
  - 📝 [Introduction](src/reference/classes/index.md) — `/reference/classes/`
    - Declaring a class
    - Instantiation
    - Identity and equality
    - Representation
  - 📝 [Fields and Constructors](src/reference/classes/fields.md) — `/reference/classes/fields/`
    - Field declarations
    - var and let fields
    - Private fields
    - Asymmetric visibility
    - Constructors
    - this. parameters
    - Initializer lists
  - 📝 [Methods and Accessors](src/reference/classes/methods.md) — `/reference/classes/methods/`
    - Methods
    - Getters and setters
    - Static members
    - Generic methods
  - 📝 [Inheritance](src/reference/classes/inheritance.md) — `/reference/classes/inheritance/`
    - extends
    - Overriding
    - abstract and final
    - Method resolution
    - Virtual dispatch
  - 📝 [Interfaces](src/reference/classes/interfaces.md) — `/reference/classes/interfaces/`
    - Declaring an interface
    - implements
    - Interface inheritance
    - Default members
    - Representation
  - 📝 [Mixins](src/reference/classes/mixins.md) — `/reference/classes/mixins/`
    - Declaring a mixin
    - on constraints
    - with clauses
    - Linearization
  - 📝 [Sealed and Case Classes](src/reference/classes/sealed.md) — `/reference/classes/sealed/`
    - sealed class
    - case declarations
    - Case class shorthand
    - Generated members
    - Exhaustive matching
  - 📝 [Extension Classes](src/reference/classes/extensions.md) — `/reference/classes/extensions/`
    - Declaring an extension
    - Resolution rules
    - Extending primitives
    - Limitations
  - 📝 [Operator Overloads](src/reference/classes/operators.md) — `/reference/classes/operators/`
    - operator ==
    - operator hash
    - Other operators
- **Errors**
  - 📝 [Exceptions](src/reference/exceptions.md) — `/reference/exceptions/`
    - throw
    - try/catch
    - finally
    - try as an expression
    - The Error class
    - Representation
- **Libraries**
  - 📝 [Libraries and Modules](src/reference/libraries.md) — `/reference/libraries/`
    - Library directories
    - Module resolution
    - Library specifiers
    - Circular imports
  - 📝 [Imports and Exports](src/reference/imports-and-exports.md) — `/reference/imports-and-exports/`
    - import
    - from … import
    - export
    - Re-exports
    - Host imports
  - 📝 [Visibility](src/reference/visibility.md) — `/reference/visibility/`
    - Module visibility
    - Class member visibility
  - 📝 [Package Manifest](src/reference/package-manifest.md) — `/reference/package-manifest/`
    - Fields
    - Dependencies
    - Targets
- **Attributes**
  - 📝 [Decorators and Intrinsics](src/reference/decorators.md) — `/reference/decorators/`
    - @intrinsic
    - @pure
    - Other attributes
    - Status
- **Standard Library**
  - 📝 [Overview](src/reference/stdlib/index.md) — `/reference/stdlib/`
    - What ships with Zena
    - Importing
    - Stability
  - 📝 [zena:array](src/reference/stdlib/array.md) — `/reference/stdlib/array/`
  - 📝 [zena:string](src/reference/stdlib/string.md) — `/reference/stdlib/string/`
  - 📝 [zena:string-builder](src/reference/stdlib/string-builder.md) — `/reference/stdlib/string-builder/`
  - 📝 [zena:map](src/reference/stdlib/map.md) — `/reference/stdlib/map/`
  - 📝 [zena:set](src/reference/stdlib/set.md) — `/reference/stdlib/set/`
  - 📝 [zena:iterator](src/reference/stdlib/iterator.md) — `/reference/stdlib/iterator/`
  - 📝 [zena:math](src/reference/stdlib/math.md) — `/reference/stdlib/math/`
  - 📝 [zena:json](src/reference/stdlib/json.md) — `/reference/stdlib/json/`
  - 📝 [zena:regex](src/reference/stdlib/regex.md) — `/reference/stdlib/regex/`
  - 📝 [zena:url](src/reference/stdlib/url.md) — `/reference/stdlib/url/`
  - 📝 [zena:fs](src/reference/stdlib/fs.md) — `/reference/stdlib/fs/`
  - 📝 [zena:console](src/reference/stdlib/console.md) — `/reference/stdlib/console/`
  - 📝 [zena:cli](src/reference/stdlib/cli.md) — `/reference/stdlib/cli/`
  - 📝 [zena:test](src/reference/stdlib/test.md) — `/reference/stdlib/test/`
  - 📝 [zena:error](src/reference/stdlib/error.md) — `/reference/stdlib/error/`
  - 📝 [zena:memory](src/reference/stdlib/memory.md) — `/reference/stdlib/memory/`
- **Toolchain**
  - 📝 [CLI](src/reference/cli.md) — `/reference/cli/`
    - zena build
    - zena run
    - zena test
    - zena fmt
    - zena lsp
    - Global options
  - 📝 [Compile Targets](src/reference/compile-targets.md) — `/reference/compile-targets/`
    - host
    - wasi
    - Target-specific behaviour
  - 📝 [Compiler Flags](src/reference/compiler-flags.md) — `/reference/compiler-flags/`
    - Output
    - Optimization
    - Encoding
    - Diagnostics
    - Debugging
  - 📝 [Formatter](src/reference/formatter.md) — `/reference/formatter/`
    - Usage
    - Formatting rules
    - Ignoring code
  - 📝 [Language Server](src/reference/language-server.md) — `/reference/language-server/`
    - Capabilities
    - Configuration
- **Appendix**
  - 📝 [Grammar](src/reference/grammar.md) — `/reference/grammar/`
  - 📝 [Keywords](src/reference/keywords.md) — `/reference/keywords/`

## /development/

- **Development**
  - ✅ [Overview](src/development/index.md) — `/development/`
    - How the project works
    - Why the language is like this
    - Where to start
  - ✅ [Built with AI](src/development/built-with-ai.md) — `/development/built-with-ai/`
    - What "almost entirely" means
    - How the loop works
    - What the language does to help
    - What has gone wrong
    - What we have learned
  - ✅ [Status and Roadmap](src/development/roadmap.md) — `/development/roadmap/`
    - Where things stand
    - What is next
    - Further out
    - What is not planned
  - ✅ [Contributing](src/development/contributing.md) — `/development/contributing/`
    - Getting set up
    - Repository layout
    - Tests and formatting
    - Working alongside agents
    - Opening a change
- **Design**
  - ✅ [Overview](src/development/design/index.md) — `/development/design/`
    - Decisions
    - The working documents
  - ✅ [Strings](src/development/design/strings.md) — `/development/design/strings/`
    - The problem: hosts disagree
    - The representation
    - What falls out of it
    - What it costs
  - ✅ [Multi-value returns](src/development/design/multi-value-returns.md) — `/development/design/multi-value-returns/`
    - The motivating case: iteration
    - What Wasm allows
    - Option still exists
    - Why not Result for errors too
  - ✅ [Unions and primitives](src/development/design/unions.md) — `/development/design/unions/`
    - Why: there is no such storage location
    - Why: there would be nothing to check at runtime
    - The visible consequence
    - What to use instead
  - ✅ [any and automatic boxing](src/development/design/any-and-boxing.md) — `/development/design/any-and-boxing/`
    - What any does today
    - The problem
    - anyref is a different thing, and it stays
    - Where this leaves generics
  - ✅ [Regular expressions](src/development/design/regex.md) — `/development/design/regex/`
    - No literal keeps the lexer context-free
    - Pay to play
    - Room to specialize later
    - The ergonomics gap, and what closes it

---

17 of 109 pages written; 92 still placeholders.
