Home

Coding Agents

While your deployed site serves /llms.txt to web tools, coding agents working in a local checkout need an index that links directly to repository files and line numbers:

luaudocs llms

This writes llms.txt at your project root, indexing your guides and every public module, type, and member linked to its declaration lines. Because it only runs extraction and markdown rendering, it requires no luaudocs init, VitePress build, or docs directory.

What it contains

Here is the llms.txt generated for this repository (indexing the guides and examples/Flux):

llms.txt

<!-- Generated by luaudocs: edits here are lost the next time `luaudocs llms` runs. -->
# LuauDocs

> Documentation generator for Luau.

This file indexes the project for coding agents reading a local copy of it, in the llms.txt format: its guides, then every module, type, and member its Luau source exposes. Links are relative to this file, and each API entry links the lines that declare it, directly below its doc comment.

Keep it current: after changing the public surface, a doc comment, or a guide, run `npx luaudocs@0.3.0 llms` in this directory and commit the result. When nothing listed here changed, the command leaves the file as it is.

## Guides

- [Getting Started](.luaudocs/guide/getting-started.md): Install LuauDocs and take a Luau library from zero to a browsable documentation site.
- [How It Works](.luaudocs/guide/how-it-works.md): How LuauDocs finds your public surface, and why your site is shaped the way it is.
- [Writing Doc Comments](.luaudocs/guide/writing-doc-comments.md): The prose layer on top of your API, and references that link themselves.
- [Overriding with Tags](.luaudocs/guide/overriding-with-tags.md): Tags correct what inference got wrong. The handful you will actually reach for.
- [Configuration](.luaudocs/guide/configuration.md): The files init writes, every luaudocs.toml key, and styling with custom.css.
- [Deploying](.luaudocs/guide/deploying.md): Publish the built site. GitHub Pages or Cloudflare Pages, base paths, and custom domains.
- [Coding Agents](.luaudocs/guide/coding-agents.md): Give coding agents an llms.txt for your repository, and have them keep it current.
- [Migrating from Moonwave](.luaudocs/guide/migrating-from-moonwave.md): Convert a Moonwave project, hand-written pages included, in one command.
- [CLI](.luaudocs/guide/reference/cli.md): Every luaudocs command and flag.
- [Tags](.luaudocs/guide/reference/tags.md): The complete tag vocabulary. Every tag is an override; none is required.
- [Markup](.luaudocs/guide/reference/markup.md): Admonitions, tabs, badges, and inline highlighting, in doc comments and guide pages alike.
- [Diagnostics](.luaudocs/guide/reference/diagnostics.md): Every diagnostic code LuauDocs can emit, and what each severity does to your build.
- [Doc Model](.luaudocs/guide/reference/doc-model.md): The JSON LuauDocs extracts from your source, and how to consume it from your own tooling.
- [Troubleshooting](.luaudocs/guide/reference/troubleshooting.md): The failures that arrive without a diagnostic code, and what to do about each.

## Flux

- [Flux](examples/Flux/init.luau): A tiny reactive state library.
- [`Flux.State: State`](examples/Flux/State.luau): [Module]
- [`Flux.Util: Util`](examples/Flux/Util/init.luau): [Module]
- [`Flux.state<T>(initial: T?): State.State<T>`](examples/Flux/init.luau#L18-L20): Creates a state holding `initial`.
- [`Flux.isState(value: any): boolean`](examples/Flux/State.luau#L20-L22): [from State] Reports whether `value` is a state.

## Flux.State

- [State](examples/Flux/State.luau): A single reactive value, and the listeners watching it. Constructors: `Flux.state`, `State.new`.
- [`type State<T>`](examples/Flux/State.luau#L6-L12): A value that notifies listeners whenever it changes.
- [`State.new<T>(initial: T?): State<T>`](examples/Flux/State.luau#L15-L17): Creates a state holding `initial`.
- [`State.isState(value: any): boolean`](examples/Flux/State.luau#L20-L22): Reports whether `value` is a state.
- [`State:Connect(callback: (any) -> ()): () -> ()`](examples/Flux/State.luau#L29-L37): Runs `callback` whenever the value changes.
- [`State:Destroy()`](examples/Flux/State.luau#L44-L46): [Deprecated since 2.0: states are collected once nothing references them] Drops every listener and releases the state.

## Flux.Util

- [Util](examples/Flux/Util/init.luau): Small helpers that stand on their own.
- [`Util.Queue: Queue`](examples/Flux/Util/Queue.luau): [Module]

## Flux.Util.Queue

- [Queue](examples/Flux/Util/Queue.luau): A queue that yields on `pop` until something is available. Constructors: `Queue.new`.
- [`type Queue<T>`](examples/Flux/Util/Queue.luau#L6-L11): A first-in, first-out queue.
- [`Queue.new<T>(): Queue<T>`](examples/Flux/Util/Queue.luau#L14-L16): Creates an empty queue.
- [`Queue:push(item: any)`](examples/Flux/Util/Queue.luau#L23-L25): [since 1.1.0] Adds `item` to the back of the queue.
- [`Queue:pop(): any`](examples/Flux/Util/Queue.luau#L28-L33): [Yields] Removes the front item and returns it, waiting when the queue is empty.

## Optional

- [Changelog](CHANGELOG.md): Notable changes to LuauDocs, newest first.

• Guides link to their local Markdown files with their frontmatter summaries.
• Each module gets a section ordered like the API reference and headed by its access path (Flux.Util.Queue), listing the module, its types, and its members.
• Every entry is a Luau signature linked to its file:line span, right below its doc comment.
• Bracketed labels carry badges ([Yields], [Server], [Read Only], [from State], and deprecation notes).
• CHANGELOG.md appears under Optional.

Because llms.txt is derived solely from committed repository files, every checkout produces identical bytes. Commit it alongside your source code.

Pointing agents at it

Reference llms.txt in your root AGENTS.md or CLAUDE.md:

AGENTS.md

## Public API

`llms.txt` indexes this library's guides and public API. Read it before using or changing the API. After changing the public surface, a doc comment, or a guide, run `npx luaudocs@0.3.0 llms` and commit the regenerated `llms.txt` with your change.

CLAUDE.md

## Public API

@llms.txt

After changing the public surface, a doc comment, or a guide, run `npx luaudocs@0.3.0 llms` and commit the regenerated `llms.txt` with your change.

Claude Code expands @llms.txt into context automatically (ideal for small libraries; for larger ones, reference llms.txt by name so agents read it on demand).

The generated llms.txt header includes the exact npx luaudocs@0.3.0 llms regeneration command, and running luaudocs llms leaves the file untouched on disk when nothing changed. When upgrading LuauDocs, regenerate llms.txt and update the version pin in your agent instructions.

Checking it in CI

Use --check in CI to fail when the committed llms.txt is missing, stale, or encounters extraction errors:

npx luaudocs@0.3.0 llms --check

A normal luaudocs llms run also aborts without overwriting llms.txt if extraction errors occur, so a temporary syntax error never strips modules from the index.

Where it lives

Pass --out <file> to write the index to another path (all relative links and the embedded regeneration command adjust automatically).

luaudocs llms only overwrites an existing file if line 1 starts with <!-- Generated by luaudocs; removing that marker claims the file as hand-maintained. Setting [docs] llms = false only disables the site's public/llms*.txt files and does not affect luaudocs llms.