# Agent Development Guide

## Build Commands
- **Debug build**: `make debug` or `meson setup build_dbg -Dbuildtype=debugoptimized && meson compile -C build_dbg`
- **Release build**: `make release` or `meson setup -Dbuildtype=release -Db_lto=true build_release && meson compile -C build_release`
- **Fast build**: `make fast` or `meson setup build_fast && meson compile -C build_fast`
- **Web build**: `make web` or `meson setup -Deditor=false -Dbuildtype=minsize build_web && meson compile -C build_web`
- **Cross-platform**: `make crosswin` (Windows), `make dockerlinux` (Linux), `make dockeremc` (Emscripten)

## Test Commands
- **Run all tests**: `meson test -C build_dbg`
- **Run single test**: `./cell tests/<test_name>` (e.g., `./cell tests/send`, `./cell tests/empty`)
- **Available tests**: spawn_actor, empty, nota, wota, portalspawner, overling, send, delay
- **Test examples**: `./cell examples/nat`, `./cell examples/http_download_actor`

## Code Style Guidelines

### C Code Style (K&R)
- **Indentation**: 4 spaces, no tabs
- **Naming**: `snake_case` for identifiers
- **Files**: Small, focused C files with header guards required
- **Formatting**: Use `.clang-format` (GNU style, 2-space continuation, attach braces)
- **Comments**: Focus on "why", keep lines to ~100 columns

### Cell Language Style (JavaScript-like)
- **Language**: Cell resembles JavaScript but has key differences - equality operators (`==`, `!=`) perform strict comparisons (equivalent to `===`, `!==` in JavaScript, no type coercion)
- **Indentation**: 2 spaces
- **Declarations**: `def` for constants, `var` for block-scoped variables (like `let`)
- **Equality**: Use `==` only (strict equality, no coercion)
- **Null checks**: Use `== null` (no `undefined` in Cell)
- **Imports**: Use `use('path')` for modules (not ES6 import/export)
- **Modules**: `*.cm` files must return values, `*.ce` files are programs (don't return)
- **Patterns**: Prefer objects, prototypes, closures over classes
- **Formatting**: Use `.prettierrc` (semicolons, double quotes, trailing commas, 1000 char width)

### File Organization
- **Modules**: `*.cm` (return objects, get frozen with `stone()`)
- **Programs**: `*.ce` (execute top-to-bottom, register handlers)
- **Naming**: Lowercase paths with `/` separators
- **Resolution**: Engine appends `.cm`/`.ce` automatically when probing

### Error Handling
- Use `log.console()` and `log.error()` for logging
- Actor system handles message timeouts automatically
- Check for circular imports (detected and reported)
- Validate module returns before freezing

### Best Practices
- Keep modules small and composable
- Use actor messaging for communication (no shared objects)
- Follow hierarchical actor system (overlings/underlings)
- Prefer functional programming patterns
- Document with `cell.DOC` system