Maintaining this guide

How the directory is put together

Editing an existing page

• The code is the source of truth. Before changing a factual claim, check it against the code (control.go, router.go, activator.go, mesh.go, controld.go, cloud.go, reaper.go, deploy/systemd/) or the design documents (docs/planet-scale.md, docs/instance-router.md). Where this guide and the code disagree, fix the guide.
• Keep the register. The guide deliberately avoids contractions, avoids unexplained jargon, spells out commands in full, and repeats key ideas where they matter. Match that when adding text.
• Keep the status badges honest. Anything not operable today must carry partially built or designed, not built, and aspirational behaviour belongs in a dashed .roadmap panel, never in running prose. When a roadmap item ships, promote its badge and move the text out of the panel in the same change.
• Use the shared components rather than inventing new markup: figure.cmd for labelled command blocks, ol.procedure for step-by-step tasks, .plain / .warn / .why panels for recaps, cautions, and rationale, and .status badges. Examples of each are on every page.

Adding a page

1. Copy an existing page as the template.

   Keep the <head>, the .frame/nav.side/main.content skeleton, the header block, and the div.sysmap. Set data-page on <body> to the new file name.

2. Add one entry to the PAGES list in guide.js, in reading order.

   That single edit updates every page’s sidebar and previous/next links. Renumber the num fields and each page’s eyebrow (“Part NN of NN”) if the new page changes the ordering.

3. Choose the system-map highlight.

   Set data-highlight on the div.sysmap to the node keys the page covers (members router instances services control updater bucket backup peer, space-separated). If the page introduces a genuinely new component, add a node for it to sysmapSVG in guide.js so the map stays a true whole-system picture.

Checking your changes

node --check docs/planet-scale-guide/guide.js     # the script must stay parseable
# then open the pages and click through:
open docs/planet-scale-guide/index.html            # macOS; or any static file server

Eyeball both color schemes (the pages follow the operating system’s light/dark preference), confirm the sidebar highlights the page you are on, and confirm the previous/next links at the bottom of each page still make sense.

Authorship marking

Per the repository’s authorship convention (CLAUDE.md), these pages were written by an LLM and carry the visible 🤖 marker in each page’s eyebrow. A human who substantially rewrites a page should remove the marker from that page (or add a person marker to certify it); an LLM editing further keeps it.

Publishing to elevenmessenger.com

The guide is published to elevenmessenger.com/infrastructure/, and this directory is the only source — nothing is ever hand-edited at the destination. Publishing is a local build, no GitHub Actions involved, in two steps:

1. Mirror this directory into the website repo.

   Run tools/sync-guide-to-website.sh <path-to-a-local-checkout-of-elevenmessenger/website>. It copies this directory into that separate, public repo’s src/infrastructure/ (Eleventy passthrough-copies it to /infrastructure/ unmodified — see that repo’s .eleventy.js), commits, and pushes the website’s main. It uses your own git credentials — no token to set up.

2. Build and publish the website.

   In that website checkout, run ./deploy.sh: it builds the Eleventy site and force-pushes the output to the gh-pages branch, which GitHub Pages serves directly (deploy-from-a-branch). The custom domain and HTTPS ride along inside the build; live within about a minute. See the website repo’s README.md § Deploy.