# Documentation

- [Introduction](/docs/introduction): Fluxon is a programming language designed for backend systems that AI agents write well.

- **Guide**
- Guide
  - [Lexical basics](/docs/guide/lexical): Comments, statements, and indentation-based blocks.
  - [Values & types](/docs/guide/values-types): The basic types — int, flt, str, bool, nil, list, map, sym, bytes — and their subtleties.
  - [Variables (bindings)](/docs/guide/variables): The two kinds of binding — `=` for locals and `<-` for reaching out of a function.
  - [Operators](/docs/guide/operators): Arithmetic, comparison, logical, and the special operators `??`, `.`, `..`, `|>`.
  - [Functions](/docs/guide/functions): Declaring functions with `fn`, returns, calling without parentheses, and lambdas.
  - [Control flow](/docs/guide/control-flow): Conditions with if/elif/else, the only loop `each`, and `match` for values.
  - [Error handling](/docs/guide/errors): The `!` propagate operator, `??` for nil, `fail` to raise, and try/catch to recover.
  - [Modules (import / export)](/docs/guide/modules): Importing batteries and your own files with `use`, aliasing with `as`, exporting with `exp`.

- **Batteries**
- Batteries
  - [http — server & client](/docs/batteries/http): Declare routes on one line, handle uploads and redirects, and call external APIs.
  - [db — database (SQLite)](/docs/batteries/db): Automatic connection, query/insert/update/upsert, transactions, idempotency, and the `tbl` schema with declarative migration.
  - [ai — LLM (first-class primitive)](/docs/batteries/ai): ai.ask, ai.json with confidence scores, the ai.run agent tool loop, and connecting any OpenAI-compatible provider.
  - [reg — function registry](/docs/batteries/reg): Store and call functions by their string name — essential for agent tools.
  - [core — list, map, str, math, rand, time](/docs/batteries/core): The core methods and modules that work without `use` — list/map methods and the str/math/rand/time functions.
  - [json](/docs/batteries/json): Encode values to JSON text and decode JSON text back to values.
  - [env — environment variables](/docs/batteries/env): Read environment variables directly with `env.NAME`.
  - [cron — scheduling](/docs/batteries/cron): Schedule work with standard Unix 5-field cron expressions, no quotes needed.
  - [queue — background queue](/docs/batteries/queue): Offload heavy work to a FIFO background worker so a webhook can respond quickly.
  - [ws — websocket (realtime)](/docs/batteries/ws): Persistent two-way connections, per-connection session state, and rooms for broadcast.
  - [log — leveled logging](/docs/batteries/log): Print to stderr with levels (debug/info/warn/err), controlled by env vars.

- **More**
- [Examples](/docs/examples): A complete small program that ties the whole language together.
- Reference
  - [For AI Agents](/docs/reference/for-agents): How to consume these docs as raw Markdown — automatically, no flags needed.
  - [Agent Spec](/docs/reference/agent-spec): The compact, canonical, token-minimal spec of the whole language — the file an AI reads to learn Fluxon.
  - [.pkg manifest format](/docs/reference/pkg-format): The optional sibling manifest that ships an AI-readable doc with a reusable Fluxon module.
- [Changelog](/docs/changelog): Notable changes to the Fluxon language and runtime, newest first.
- [Roadmap](/docs/roadmap): The path to a real, working programming language — from stability to distribution.