Where the rest of the documentation lives
This manual is for people using melee. The repository holds a second set of documents, written for the people building it.
If you are reading the published site, these are files in the melee repository rather than pages here. They are listed because a question this manual answers with “it works like this” is often answered there with “and here is why, and what we measured”.
In the repository
| Path | What |
|---|---|
README.md | The repository itself: layout, toolchain, everyday commands. |
PLAN.md | Roadmap: milestones, what is built, what is next. |
TASKS.md | The task list. Every SEC-*, P-* and milestone task referenced in this manual is defined here. |
docs/proposal.md | The founding proposal. Historical — parts of it were superseded by what got built. |
docs/design/architecture.md | How the pieces fit, written for contributors. The source of most of How a request reaches your app. |
docs/design/supervisor.md, activation.md, protocol.md | The Rust server, the warm-process strategy, and the frame protocol apps speak. |
docs/design/stdlib.md | The layer map from the app-facing DSL down to the frames. |
docs/design/persistent.md | The full design of durable objects. |
docs/design/security.md | The threat model, trust boundaries, attacker positions and the findings table. This is the document behind Keeping it safe. |
docs/design/ergonomics.md | Why the app-facing surface is shaped the way it is. |
docs/design/first-app.md, at-here-port.md | The two real apps, and what porting one taught. |
docs/decisions/ | Architecture decision records, numbered. Short, and the best answer to “why is it like that”. |
docs/research/spinel.md | Every Spinel trap found so far, with a workaround for each. If the compiled app and melee dev disagree, read this. |
docs/research/cruby-vs-spinel.md | Where the two runtimes differ. |
docs/research/m*-results.md | Measurements, per milestone, with dates. The numbers quoted in this manual come from here. |
examples/kitchen/, examples/at-here/ | Two complete apps. Worth reading before writing your own. |
stdlib/README.md | The standard library’s own internals, including the rules that keep it compiling. |
The decision records
Worth knowing these exist, because they explain most of the constraints this manual describes:
| 0002 | HTTP is terminated in the supervisor; apps speak frames over a socket pair |
| 0005 | Fibers only, no threads, as a platform rule |
| 0006 | The library runs under both CRuby and Spinel: develop on CRuby, deploy on Spinel |
| 0008 | Activation is warm-process fork, with the sandbox applied before exec |
| 0010 | The app boundary is a typed request and response, not Rack |
| 0011 | Durable objects have explicit per-object storage; no checkpointed instance variables |
| 0014 | A TLS edge in front, owning TLS and custom domains |
| 0015 | A uid per app, and a Landlock allow-list rather than a read-only root |
Building this manual
The markdown under docs/guide/ is the canonical form. mise run docs assembles it and builds the HTML into
docs/site/; mise run docs:serve does the same with live reload.
Two files in it are generated and committed, and mise run docs:check fails if either is stale:
stdlib/docs/reference.md | from stdlib/sig/*.rbs, by stdlib/bin/melee-docs-api |
docs/guide/llms.txt | from docs/guide/SUMMARY.md, by scripts/docs-index.rb |
docs/guide/reference/ is a symbolic link to stdlib/docs/, so the API pages live with the library they
document and still read correctly from either place.