A getting-started guide in the capabilities style, for users who want to write effect routines ahead of a packaged library. Covers the program shape, native and reifying contexts, driving from a foreign host, keeping foreign values out of the core (the !Send shell), fan-out, testing, rules, and a checklist for adding a capability. Appendix A shows the effects and coeffects styles as kinds of capability; Appendix B is a glossary.

Build #

The PDF is checked in beside the sources. To refresh it after editing:

nix run .#refresh-guide

(nix build .#guide alone produces it under result/ without touching the tracked copy.)

Inside nix develop, latexmk -pdf how-to-write-effect-routines.tex (add -pvc to watch) does the same in place.

Layout #

how-to-write-effect-routines.tex   entry point
preamble.tex                       packages, palette, listings, TikZ styles
sections/                          one file per section; appendices prefixed a-, b-

Code examples are taken from hosts/capabilities/, hosts/effects/, hosts/coeffects/ and compare/capabilities/, lightly trimmed. When the code changes, the guide should too.