Lua teaches direct tables, small functions, metatables, coroutines, nil, and host embedding. Musi keeps the small-language feel, but refuses to put every idea into a table convention. Record shape, data variants, behavior classes, effects, and foreign declarations stay separate so the compiler can follow them.
Use this guide as a translation journal for Lua code. Start with the familiar habit, then ask which Musi construct owns the same promise. A page is successful when it tells you which old instinct to keep and which old shortcut to drop.
Start from the habit that hurts
- Values, Locals, and Expressions - values habits get translated once, then the Musi Book owns the details.
- Functions, Closures, and Named Calls - values habits get translated once, then the Musi Book owns the details.
- Blocks, Branching, and Repetition - blocks habits get translated once, then the Musi Book owns the details.
- Tables, Records, and Field Updates - records habits get translated once, then the Musi Book owns the details.
- Arrays, Sequences, Maps, and Pipelines - arrays habits get translated once, then the Musi Book owns the details.
- Nil, Option, and Result - absence and failure stop being side channels.
- Errors, Pcall, and Effects - outside work becomes a named request.
- Coroutines and Effect Boundaries - outside work becomes a named request.
- Metatables, Classes, Instances, and Laws - records habits get translated once, then the Musi Book owns the details.
- Pattern Matching and Data Variants - patterns habits get translated once, then the Musi Book owns the details.
- Modules, Imports, and Exports - package boundaries replace compatibility-era habits.
- Testing and Tooling - testing habits get translated once, then the Musi Book owns the details.
- Embedding, C API, and FFI - native edges stay narrow enough to audit.
Habits that still help
- Keep the Lua habit of using small names and simple values.
- Drop table/metatable shortcuts when Musi can name shape, behavior, absence, or host calls directly.
- Keep examples tied to ordinary work: receipts, routes, files, animals, people, rooms, and services.
First false friend
Musi class is not a metatable pattern; records/data hold table-like shape, classes/instances name promised behavior. If you need a person, car, invoice, or package, start with records or data. If you need any type that can compare, show, encode, or step, use a class with instances.
When to switch to the Musi Book
Stay in this guide while a Lua habit is getting in the way. Switch to Values and let, Records, Patterns, Generics, Classes, and Effects when you need the source-of-truth rule.