# Documentation

> The map of the documentation grouped by intent: start here, understanding the design, measurements, the project record, and the Mojo framework underneath.

Pages grouped by what you are trying to do. For the project's current state,
run the command rather than reading a file: `uv run poe milestones` computes
what remains before 1.0 from [SPEC.md](https://m0serve.dev/docs/spec.md) and the roadmap's Known
issues, and CI prints it on every pull request.

## Start here

| page | what it answers |
|---|---|
| [QUICKSTART.md](https://m0serve.dev/quickstart.md) | **Show me.** Ten minutes from `pip install` to live multi-tab sync from one sync Django file. Every command is executed by CI. |
| [demo.m0serve.dev](https://demo.m0serve.dev) | **Show me without installing anything.** The quickstart's two-tab sync, live: a held SSE stream and a WebSocket side by side from one sync Django file, with the serving version on the page. [apps/demo](https://github.com/codetalcott/mojo-http/blob/main/apps/demo/README.md) is the file, [deploy/demo](https://github.com/codetalcott/mojo-http/blob/main/deploy/demo/README.md) the deployment. |
| [RUNNING.md](https://m0serve.dev/docs/running.md) | **How do I run my app?** Flags, the execution modes and when each applies, what to put in front of it, shutdown and exit codes. |
| [SPEC.md](https://m0serve.dev/docs/spec.md) | **What can it do, and what proves it?** One row per capability with the CI gate that proves it. The closest thing to a contract. |

## Understanding the design

| page | what it answers |
|---|---|
| [WSGI_VS_ASGI.md](https://m0serve.dev/docs/wsgi-vs-asgi.md) | Why there are two execution modes, in a page: what each is for, what free-threading changes, and where each has a cliff. |
| [WSGI_CONFORMANCE.md](https://m0serve.dev/docs/wsgi-conformance.md) | Where the WSGI implementation stands against PEP 3333, clause by clause. |
| [ROADMAP.md](https://m0serve.dev/docs/roadmap.md) | The project's state: milestones, known issues with what retires each, what is not planned and why. |
| [Design notes](https://m0serve.dev/docs/roadmap.md#design-notes) | The engineering record behind the decisions: long-form, dated, kept as written. |

## Measurements

Records of something measured, with the environment it was measured in. They
are not tutorials, and they age.

| page | what it answers |
|---|---|
| [BENCHMARKS.md](https://m0serve.dev/docs/benchmarks.md) | Where m0serve wins and loses against gunicorn, uvicorn and Granian, and how not to be fooled by a server benchmark. |
| [WSGI_PERFORMANCE.md](https://m0serve.dev/docs/wsgi-performance.md) | The WSGI and ASGI numbers, rendered from dated artifacts. |
| [SERVER_PERFORMANCE.md](https://m0serve.dev/docs/server-performance.md) | The Mojo server's own numbers, without Python in the path. |
| [REAL_APP_VALIDATION.md](https://m0serve.dev/docs/real-app-validation.md) | The soak: this server against Django projects nobody here wrote. |

## The project

| page | what it answers |
|---|---|
| [../CHANGELOG.md](https://m0serve.dev/changelog.md) | What changed, and when. |
| [RELEASING.md](https://m0serve.dev/docs/releasing.md) | How a release happens, and the two gates CI cannot run. |
| [../README.md](https://m0serve.dev/readme.md) | The repository as a whole, including the Mojo framework m0serve is one package of. |
| [../PROVENANCE.md](https://m0serve.dev/provenance.md) | Where the code came from, and the licensing record. |

## The Mojo framework

For people building on `mojo-http` directly rather than serving a Python app.

| page | what it answers |
|---|---|
| [FFI_DISTRIBUTION.md](https://m0serve.dev/docs/ffi-distribution.md) | What ships in the C-ABI bundle, and the licensing position. |
| [SQLITE_PERFORMANCE.md](https://m0serve.dev/docs/sqlite-performance.md) | m0-sqlite findings: batch writes, `mmap_size`, `json_each`. |
| [sqlite-vtab-feasibility.md](https://m0serve.dev/docs/sqlite-vtab-feasibility.md) | Whether virtual tables are reachable from Mojo. |

## This site

Everything here renders to [m0serve.dev](https://m0serve.dev) by
[scripts/docsite.py](https://github.com/codetalcott/mojo-http/blob/main/scripts/docsite.py), served by m0serve itself, with
`llms.txt` and a Markdown twin of every page for agents and a sitemap for
crawlers. A new `docs/*.md` must be listed in the generator's page table, or
`check-docs` fails naming it; notes under `docs/notes/` are picked up on
their own. [deploy/site](https://github.com/codetalcott/mojo-http/blob/main/deploy/site/README.md) is the deployment.
`spec.json` is generated from `SPEC.md` by `poe render-spec`; edit the tables,
never the JSON.