# santoku

> santoku is a Lua 5.1 framework for building applications end to end in one language: a dependency-light base library, a build and release harness (toku), build-time templates, bundling to native and WebAssembly targets, browser and server runtimes, and libraries for sqlite, cryptography, parsing, sockets, and machine learning.

## About

santoku is developed as a set of independently versioned Lua rocks that share one toolchain. The documentation site is itself a santoku project, and its interactive examples run the base library in a Lua interpreter compiled to WebAssembly.

## Lua version

santoku targets Lua 5.1, because 5.1 is the version its platforms actually share. LuaJIT implements 5.1 and OpenResty embeds LuaJIT, so server code, client code and the build harness all run the same language. Compiled to WebAssembly, the 5.1 core is smaller to embed, and its single number type sidesteps the integer and float split introduced in 5.3, which keeps numeric values crossing the JavaScript boundary simple. Support for newer versions is meant to come from compatibility shims layered over the 5.1 core rather than version branches in the tree; contributions and design ideas for that layer are welcome.

## Full reference

This file is the index, at https://santoku.dev/llms.txt. Each entry below links one tab's own llms.txt, which carries every documented example on that tab with its prose and code and fits in a single fetch. https://santoku.dev/llms-small.txt has every tab's introduction and example titles on one page. Fetch the tab you need and read it before inferring an API from surrounding code.

## Agent skills

https://santoku.dev/AGENTS.md is the same guidance as a single AGENTS.md file, for any agent that reads one. https://santoku.dev/skills.txt is the machine-readable bundle that toku skills installs into ~/.claude/skills for Claude Code and ~/.codex for Codex.

## Getting started

- [Install](https://santoku.dev/install/llms.txt): provision toku with setup-toku.sh: download it, read it, run it, then verify with toku doctor (page: https://santoku.dev/install)
- [Getting started: a library](https://santoku.dev/start-lib/llms.txt): scaffold, build, test and publish a Lua rock with toku: the descriptor, templated sources, C extensions, specs, and a release that pushes to git, hosts the tarball on GitHub and uploads the rockspec to luarocks (page: https://santoku.dev/start-lib)
- [Getting started: a web app](https://santoku.dev/start-web/llms.txt): scaffold a full-stack web app, WebAssembly client plus OpenResty server in one repository: every file toku init --web produces, the configure hook, and the dev loop (page: https://santoku.dev/start-web)
- [Getting started: a server API](https://santoku.dev/start-server/llms.txt): a JSON API with no frontend: every file toku init --api produces, server-side SQLite under OpenResty in WAL mode, one connection and prepared statements per nginx worker, and native specs against :memory: (page: https://santoku.dev/start-server)

## Core

- [santoku](https://santoku.dev/santoku/llms.txt): the base library: arrays, strings, tables, functions, numbers, and fractional order keys (page: https://santoku.dev/santoku; luarocks: https://luarocks.org/modules/birchpointswe/santoku)

## Web and servers

- [santoku-web](https://santoku.dev/santoku-web/llms.txt): browser runtime for Lua compiled to WebAssembly: val and js interop, promise await, and batched DOM access over a command buffer (page: https://santoku.dev/santoku-web; luarocks: https://luarocks.org/modules/birchpointswe/santoku-web)
- [santoku-http](https://santoku.dev/santoku-http/llms.txt): transport-agnostic HTTP client front end: retry with jittered backoff, cancellation, query params, and request/response hooks over a pluggable socket backend (page: https://santoku.dev/santoku-http; luarocks: https://luarocks.org/modules/birchpointswe/santoku-http)
- [santoku-resty](https://santoku.dev/santoku-resty/llms.txt): OpenResty glue: santoku-flavored wrappers over lua-resty HTTP clients, RS256 and ES256 JWTs over santoku-jwt, and the OpenResty WebSocket backend (page: https://santoku.dev/santoku-resty; luarocks: https://luarocks.org/modules/birchpointswe/santoku-resty)
- [santoku-websocket](https://santoku.dev/santoku-websocket/llms.txt): one WebSocket API over a pluggable transport: callbacks, text and binary sends, queueing until open, and reconnect, with native, OpenResty and browser backends (page: https://santoku.dev/santoku-websocket; luarocks: https://luarocks.org/modules/birchpointswe/santoku-websocket)
- [santoku-mysql](https://santoku.dev/santoku-mysql/llms.txt): MySQL and MariaDB client with santoku-sqlite's API: server-side prepared statements, verified TLS, and native and OpenResty cosocket transports (page: https://santoku.dev/santoku-mysql; luarocks: https://luarocks.org/modules/birchpointswe/santoku-mysql)
- [santoku-tls](https://santoku.dev/santoku-tls/llms.txt): TLS 1.3 on a socket you already own, with self-signed P-256 keys pinned by SPKI hash, as a Lua module and a header-only C API over OpenSSL 3 (page: https://santoku.dev/santoku-tls; luarocks: https://luarocks.org/modules/birchpointswe/santoku-tls)
- [santoku-socket](https://santoku.dev/santoku-socket/llms.txt): HTTP(S) client: blocking fetch, cancelable request/await handle, and millisecond sleep over LuaSocket and LuaSec (page: https://santoku.dev/santoku-socket; luarocks: https://luarocks.org/modules/birchpointswe/santoku-socket)
- [santoku-cdp](https://santoku.dev/santoku-cdp/llms.txt): Chrome DevTools Protocol client: attach to a page, navigate, evaluate JavaScript, wait for elements and take screenshots, plus a toku-browser command (page: https://santoku.dev/santoku-cdp; luarocks: https://luarocks.org/modules/birchpointswe/santoku-cdp)
- [santoku-imap](https://santoku.dev/santoku-imap/llms.txt): IMAP4rev1 client over an injected stream driver: search, fetch with bodystructure, append, and companion modules for header decoding, message text, and threading (page: https://santoku.dev/santoku-imap; luarocks: https://luarocks.org/modules/birchpointswe/santoku-imap)

## Data and machine learning

- [santoku-sqlite](https://santoku.dev/santoku-sqlite/llms.txt): SQLite for Lua: prepared-statement query closures, transactions, zero-copy carray vector binds, FTS5 full-text search over santoku tokens, and fully encrypted databases (page: https://santoku.dev/santoku-sqlite; luarocks: https://luarocks.org/modules/birchpointswe/santoku-sqlite)
- [santoku-sqlite sync](https://santoku.dev/santoku-sqlite-sync/llms.txt): peer-to-peer sync for tables you already have: trigger-captured writes, last-writer-wins over a hybrid logical clock, transport left to the application, and two peers converging in-process with no network (page: https://santoku.dev/santoku-sqlite-sync; luarocks: https://luarocks.org/modules/birchpointswe/santoku-sqlite)
- [santoku-sqlite-migrate](https://santoku.dev/santoku-sqlite-migrate/llms.txt): versioned, idempotent SQL migrations for santoku-sqlite: one function that applies missing migrations in version order, forward-only, in a single transaction (page: https://santoku.dev/santoku-sqlite-migrate; luarocks: https://luarocks.org/modules/birchpointswe/santoku-sqlite-migrate)
- [santoku-matrix](https://santoku.dev/santoku-matrix/llms.txt): typed numeric vectors, dense and sparse matrices, bit matrices, and top-k retrieval: the C data layer under santoku search and ML (page: https://santoku.dev/santoku-matrix; luarocks: https://luarocks.org/modules/birchpointswe/santoku-matrix)
- [santoku-learn](https://santoku.dev/santoku-learn/llms.txt): machine learning toolkit: n-gram tokenization, gazetteer matching, booleanization, spectral embeddings, ridge regression, and calibrated decisions (page: https://santoku.dev/santoku-learn; luarocks: https://luarocks.org/modules/birchpointswe/santoku-learn)
- [santoku-learn-llama](https://santoku.dev/santoku-learn-llama/llms.txt): llama.cpp binding: gguf model embeddings as dense fvec codes for the santoku-learn pipeline, plus a minimal raw and chat text generator (page: https://santoku.dev/santoku-learn-llama; luarocks: https://luarocks.org/modules/birchpointswe/santoku-learn-llama)

## Build and test

- [santoku-make](https://santoku.dev/santoku-make/llms.txt): the project build harness behind toku: a dependency-graph engine, a descriptor-driven project layer for lib, bin, and web packages, the four ways code is gated out of or varied for WebAssembly builds, and LICENSE and SPDX header management (page: https://santoku.dev/santoku-make; luarocks: https://luarocks.org/modules/birchpointswe/santoku-make)
- [santoku-cli](https://santoku.dev/santoku-cli/llms.txt): the toku command line: build, test, install, release, license notices, and scaffolding for santoku projects (page: https://santoku.dev/santoku-cli; luarocks: https://luarocks.org/modules/birchpointswe/santoku-cli)
- [santoku-test-runner](https://santoku.dev/santoku-test-runner/llms.txt): the spec runner behind toku test: recursive test/spec discovery, Lua-pattern file matching, per-file interpreter isolation, and the conventions for writing santoku specs (page: https://santoku.dev/santoku-test-runner; luarocks: https://luarocks.org/modules/birchpointswe/santoku-test-runner)
- [santoku-bundle](https://santoku.dev/santoku-bundle/llms.txt): bundles a Lua entry script and its dependencies into one C program compiled to a native executable or WASM via emcc (page: https://santoku.dev/santoku-bundle; luarocks: https://luarocks.org/modules/birchpointswe/santoku-bundle)

## System and crypto

- [santoku-fs](https://santoku.dev/santoku-fs/llms.txt): filesystem library: whole-file and streamed I/O, path string helpers, traversal iterators, and a POSIX C extension, all raising structured errors (page: https://santoku.dev/santoku-fs; luarocks: https://luarocks.org/modules/birchpointswe/santoku-fs)
- [santoku-system](https://santoku.dev/santoku-system/llms.txt): process spawning and POSIX glue: fork programs or Lua functions across parallel jobs and stream their output as iterators (page: https://santoku.dev/santoku-system; luarocks: https://luarocks.org/modules/birchpointswe/santoku-system)
- [santoku-monocypher](https://santoku.dev/santoku-monocypher/llms.txt): Monocypher crypto bindings: diceware passphrases, Argon2id identities, EdDSA request signing, XChaCha20-Poly1305 AEAD keys, HMAC helpers (page: https://santoku.dev/santoku-monocypher; luarocks: https://luarocks.org/modules/birchpointswe/santoku-monocypher)
- [santoku-jwt](https://santoku.dev/santoku-jwt/llms.txt): JSON Web Tokens over a pluggable crypto backend: ES256 everywhere through santoku-monocypher, RS256 under OpenResty, claim checks, and cached remote JWKS (page: https://santoku.dev/santoku-jwt; luarocks: https://luarocks.org/modules/birchpointswe/santoku-jwt)

## Text and templates

- [santoku-template](https://santoku.dev/santoku-template/llms.txt): compile-once template engine: text with embedded Lua blocks rendered against an env, the engine behind .tk file expansion in the toku build harness (page: https://santoku.dev/santoku-template; luarocks: https://luarocks.org/modules/birchpointswe/santoku-template)
- [santoku-lpeg](https://santoku.dev/santoku-lpeg/llms.txt): parsing and text transformation helpers built on a vendored LPeg: JSON field streaming, HTML scanning, injection, minification, and a subsequence-safe comment stripper (page: https://santoku.dev/santoku-lpeg; luarocks: https://luarocks.org/modules/birchpointswe/santoku-lpeg)
- [santoku-mustache](https://santoku.dev/santoku-mustache/llms.txt): mustache template rendering in C: compile once, render Lua values to strings, with sections, partials, and dedent (page: https://santoku.dev/santoku-mustache; luarocks: https://luarocks.org/modules/birchpointswe/santoku-mustache)
- [santoku-markdown](https://santoku.dev/santoku-markdown/llms.txt): Markdown to HTML rendering: a C binding to Sundown exposing a single to_html function (page: https://santoku.dev/santoku-markdown; luarocks: https://luarocks.org/modules/birchpointswe/santoku-markdown)

## Optional

- [llms-full.txt](https://santoku.dev/llms-full.txt): every tab in one file, for tools that download the whole reference; too large for a single WebFetch call