Mix — manual

The reference manual for the Mix language, one page per topic. The canonical home of these pages is docs/mix/ in the public markc/cosmix monorepo; add a page by dropping TOPIC.md there. The same files render everywhere:

Terminal — mix man TOPIC (mix man alone prints this index). Online source with a local $COSMIX/docs/mix fallback and a 24 h cache at ~/.cache/cosmix/man/.
Web — cosmix.dev/mix serves this directory.
GitHub — browse docs/mix/ directly; this file doubles as the directory README.
Local clone — plain markdown with relative links; any editor or viewer works.

New to Mix, or coming from bash/Python/JS? Read gotchas first — it is the errata against every other language's reflexes, and every row of its table is executed by cargo test -p cosmix-mix --test man_gotchas, so it cannot rot. mix man syntax is the mental model; gotchas is the corrections.

Start here

overview — what Mix is, why it exists, where it came from.
invocation & CLI — mix file, -c, -, -i, login shell, --serve, flags.
the mix command — mix help/man/builtins/what/status/trace/… meta-commands.
syntax & the classifier — tokens, the newline rule, shell-vs-Mix dispatch.
gotchas — the guesses from bash/Python/JS that are silently wrong here. Read it first.

The language

variables, sigils & scope — $ sigils, ${...}, function-local binding.
strings — 'raw' vs "interp", .. concat, codepoint/byte/grapheme ops.
numbers — f64, radix literals, ordering, coercion.
operators — arithmetic, comparison, and/or/not, .., ?:, ??.
control flow — if/while/for/loop, if-as-expression, break/continue.
functions, lambdas & modules — fn, closures, the pass-in/return/reassign triad.
modules — require/include/source — require() isolated module loading vs the splice loaders.
lists & maps — literals, indexing, push/pop, the base footguns.
higher-order functions — map/filter/reduce/sort_by/group_by/…
errors & exit handling — try/catch/die/panic, run_rc().rc, timeouts.

Builtins & I/O

math — rounding, powers, logs, trig, min/max/clamp, constants.
files & I/O — read_file/write_file/glob/stat/chmod/walk/…
processes & system — run/run_rc/run_stream/spawn/env/exit/…
job control — foreground/background jobs, suspension, resume (interactive).
data & serialization — JSON, TOML, jq, data_encode, strict-data .mix.
byte buffers — buffer/buffer_push/freeze, the one reference-semantic type.
regular expressions — re_match/re_find/re_replace/re_split/grep_lines (subject first).
dates & time — time/date_format/now_iso/duration_format.
http — http_get/http_post/http_request, deadlines.
datastar — ds_* SSE event framing.
archives — tar_list/tar_unpack/tar_pack, zstd/gzip/none, safe staged extraction.

Mesh & runtime

Bus messaging — send/emit/address/on, $result/$rc bands, the mesh.
serving as a citizen — mix --serve service.mix, the supervised runtime.
remote execution (ssh) — ssh_run/ssh_must/ssh_mix, env transports.
capabilities & embedding — the capability classes + sandbox model.
expression evaluation mode — eval_expr_string(), the single-expression rule, the static deny walk.

Reference

builtin index — every builtin by category.
lint diagnostics — every MIX-XXXX code and its story.
reserved words — the keyword set, keywords-as-names.
shell-dispatch mode — pipes, &&, brace expansion, $(...), redirects.
owned interactive editor — MIX_EDITOR=owned (preview).
usage statistics — runtime modes, report windows, persistence, kill switch, static coverage.

Design docs & specs

Design docs, background rationale, and the formal specs (04 language reference, 18 citizen runtime) all live in the operator control repo since 2026-07-23; this manual is the complete public reference.