# Lilush documentation reference

## Overview

_Lilush_ is a statically compiled LuaJIT interpreter for Linux that 
bundles a curated collection of Lua modules and C libraries. It has two builds:

1. `lilu` - A batteries-included LuaJIT runtime with networking, crypto, terminal I/O, and system utilities
2. `lilush` - A feature-rich Linux shell _Lilush Shell_, built on top of `lilu`

Lilush is by design Linux only and not portable.

## Documentation index

* [ARCHITECTURE](docs/ARCHITECTURE.md): Detailed architecture overview
* [CONVENTIONS](docs/CONVENTIONS.md): Coding and naming conventions used in the project
* [DEVELOPMENT](docs/DEVELOPMENT.md): Building & testing instructions; build system architecture
* [LEV](docs/LEV.md): LEV async I/O runtime (event loop, UDP/TCP sockets, timers, combinators)
* [LITLS](docs/LITLS.md): Lilush TLS stack (crypto primitives, X.509, TLS 1.3 protocol, Lua API)
* [DNS](docs/DNS.md): DNS client API, record types, cache, transports
* [GFX](docs/GFX.md): Terminal graphics (Kitty protocol), pixel canvas, sprites, pixel fonts, on-screen display, frame loop
* [SOUND](docs/SOUND.md): Audio module (raw ALSA PCM playback, float32 sample buffers, in-process mixer, WAV loader, synth)
* [SPEECH](docs/SPEECH.md): English text-to-speech (Klatt-style formant synthesizer, voice presets/knobs, deterministic)
* [MNEME](docs/MNEME.md): MNEME embedded key-value database
* [WIKIDB](docs/WIKIDB.md): Wiki-DB convention for self-describing MNEME wiki databases
* [LILPACK](docs/LILPACK.md): LILPACK package system (convention, packer, management, shell integration)
* [COMPLETION](docs/COMPLETION.md): Completion engine (provider/source/renderer interfaces, input integration)
* [LEM](docs/LEM.md): LEM text editor (modal editing, piece table, syntax highlighting, buffers, commands)
* [SHELL](docs/SHELL.md): Lilush Shell (startup, config, modes, prompt, builtins, key bindings)
* [LSH](docs/LSH.md): LSH script format (syntax, arguments, builtins, differences from bash)
* [TSS](docs/TSS.md): TSS (Terminal Style Sheets) semantics, properties, cascading, and API contract
* [THEMES](docs/THEMES.md): Theme system, live reloading, creating custom themes
* [REDIS](docs/REDIS.md): Redis client API and connection config contract
* [CREDITS](docs/CREDITS.md): Credits, acknowledgements, licensing info

## Entry Points

The `lilush` binary has multiple entry modes:

1. **Interactive shell**: `lilush` (no args)
2. **Script execution**: `lilush /path/to/script.lua [args]`
   - Example: `lilush myscript.lua arg1 arg2`
3. **Lua code execution**: `lilush -e '<lua-code>'`
   - Executes Lua code directly (like `python -e` or `ruby -e`)
   - Example: `lilush -e "print('Hello from Lua')"`
   - Example: `lilush -e "local std = require('std'); print(std.fs.cwd())"`
4. **Shell command mode**: `lilush -c <shell-commands>`
   - Executes lilush shell commands (mimics bash `-c` behavior)
   - Example: `lilush -c "echo hello"`
   - **Note**: This runs shell commands, NOT Lua code. Use `-e` for Lua code.
5. **Built-in mode**: Symlinked as builtin name executes that builtin
6. **Version**: `lilush -v`

See `buildgen/entrypoints/lilush/main.c` for implementation.

The minimal build, `lilu` has only (2), (3) and (6) entry modes from the above.

## Common Gotchas

1. **LuaJIT is not Lua 5.3+** - Uses Lua 5.1 + some 5.2 compat.
2. **Static linking** - All dependencies must be statically linkable. 
   Dynamic loading (`require` with .so) won't work in final binary.
3. **FFI disabled** - LuaJIT FFI is disabled (`-DLUAJIT_DISABLE_FFI`) for size/security. Use C modules instead.
4. Built with [musl libc](https://musl.libc.org/), not glibc.