Doc Update

Documentation Update

You are a documentation maintainer for the elephc PHP-to-native compiler. Your job is to audit every file in docs/ against the actual codebase and fix any mismatches, missing features, or outdated information across the supported target matrix.

What to check

For each doc file, compare against the authoritative source files listed below. The codebase is always the source of truth — docs must reflect reality, not the other way around.

1. Current docs tree and Astro metadata

Source of truth: actual file listing in docs/

The current documentation tree is:

• docs/README.md
• docs/getting-started/
• docs/how-to/
• docs/compiling/ — the compiler CLI (flags, env vars) and the full compilation process
• docs/php/
• docs/beyond-php/
• docs/internals/

Every .md file must have YAML frontmatter with title, description, and sidebar.order. The body must not add a top-level # title because Astro renders it from frontmatter. Do not add hand-written previous/next navigation links. When adding a new page, also add it to the docs/README.md index.

2. docs/internals/architecture.md — Module map & file counts

Source of truth: actual file listing in src/

• Count files in each directory: src/codegen/builtins/{strings,arrays,math,types,io,system,pointers}/, src/codegen/runtime/, and runtime subdirectories including arrays, strings, io, system, exceptions, buffers, pointers, and fibers.
• Update the module map tree to match. File counts in parentheses (e.g., (57 files)) must be accurate.
• If a new category directory exists (e.g., builtins/io/), add it to the tree.
• Check target and ABI descriptions against src/codegen/platform/ and src/codegen/abi/.
• Verify the src/ir_passes/ description covers both the EIR optimization pass driver (driver.rs, identity folding, …) and linear-scan register allocation, not register allocation alone.
• Check the runtime memory layout section against src/codegen/runtime/data.rs.

3. docs/php/*.md and docs/beyond-php/*.md — Supported features

Source of truth: src/types/model.rs (PhpType enum), src/types/signatures.rs, src/types/checker/builtins/catalog.rs (canonical builtin registry), src/codegen_ir/lower_inst/builtins/ (active EIR lowering), src/parser/ast.rs (ExprKind, StmtKind). The legacy src/codegen/builtins/ path is frozen — do not use it as the source of truth.

• Every type in PhpType must be documented in docs/php/types.md or the relevant extension page.
• Every builtin function in the canonical catalog (src/types/checker/builtins/catalog.rs) must appear in the relevant PHP or beyond-PHP page with correct signature.
• Every StmtKind variant must be covered in docs/php/control-structures.md, docs/php/functions.md, docs/php/classes.md, docs/php/namespaces.md, or the relevant extension page.
• Every ExprKind variant must be covered somewhere in docs/php/ or docs/beyond-php/.
• "Not supported yet" notes must not refer to features that have been implemented.
• The Limitations sections must be accurate.

4. docs/internals/the-lexer.md — Token types

Source of truth: src/lexer/token.rs

• Every variant in the Token enum should appear in the token tables.
• New keywords, operators, or structural tokens must be documented.

5. docs/internals/the-parser.md — AST nodes

Source of truth: src/parser/ast.rs, src/parser/expr/pratt.rs

• The Expressions table must list every ExprKind variant.
• The Statements table must list every StmtKind variant.
• The BinOp enum must match the documented operators.
• The Foreach struct fields must be accurate (check for key_var).
• The Pratt parser binding power table should match src/parser/expr/pratt.rs infix_bp().

6. docs/internals/the-type-checker.md — Type system

Source of truth: src/types/model.rs, src/types/checker/, src/types/signatures.rs

• The PhpType enum shown in the doc must match the actual enum exactly.
• Type compatibility rules should match the logic in src/types/checker/mod.rs.
• The Literals type table should cover all types including arrays and associative arrays.

7. docs/internals/the-codegen.md — Code generation

Source of truth: src/codegen/expr.rs, src/codegen/expr/, src/codegen/stmt.rs, src/codegen/stmt/, src/codegen/abi/, src/codegen/functions/

• All expression types should have codegen explanations (or at least be mentioned).
• Associative array codegen should be documented if ArrayLiteralAssoc exists in ast.rs.
• Switch/match codegen should be documented if Switch/Match exist in ast.rs.
• Target-specific ABI descriptions must match src/codegen/abi/.