| 1 | <!doctype html> |
| 2 | <html lang="en"> |
| 3 | <head> |
| 4 | <meta charset="utf-8" /> |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| 6 | <title>Maintaining this guide — Running the fleet</title> |
| 7 | <link rel="stylesheet" href="guide.css" /> |
| 8 | <script src="guide.js" defer></script> |
| 9 | </head> |
| 10 | <body data-page="README.html"> |
| 11 | <div class="frame"> |
| 12 | <nav class="side"></nav> |
| 13 | <main class="content"> |
| 14 | <div class="wrap"> |
| 15 | |
| 16 | <header class="top"> |
| 17 | <p class="eyebrow"><span class="robot">🤖</span> Running the fleet · About this guide</p> |
| 18 | <h1>Maintaining this guide</h1> |
| 19 | <p class="thesis">The guide is ten plain HTML pages, one shared stylesheet, and one shared script — <strong>no build step, no dependencies, nothing to install</strong>. Open any page in a browser straight from the repository, or serve the directory statically. This page explains how to keep it accurate and how to extend it.</p> |
| 20 | </header> |
| 21 | |
| 22 | <h2 id="layout">How the directory is put together</h2> |
| 23 | <div class="tablewrap"> |
| 24 | <table> |
| 25 | <tr><th>File</th><th>Role</th></tr> |
| 26 | <tr><td><code>index.html</code> … <code>reference.html</code></td><td>The ten content pages. Each is self-contained semantic HTML; nothing is generated.</td></tr> |
| 27 | <tr><td><code>guide.css</code></td><td>The single stylesheet. Colors, typography, panels, badges, tables, diagrams — edit here and every page follows. Light and dark themes are both defined at the top.</td></tr> |
| 28 | <tr><td><code>guide.js</code></td><td>The single script, and the guide’s one source of structure: the <code>PAGES</code> list (which drives the sidebar and the previous/next links on every page) and the shared “you are here” system-map diagram. All injected markup is built from static in-code strings only, per the repository rule about <code>innerHTML</code>.</td></tr> |
| 29 | <tr><td><code>README.html</code></td><td>This page.</td></tr> |
| 30 | </table> |
| 31 | </div> |
| 32 | |
| 33 | <h2 id="editing">Editing an existing page</h2> |
| 34 | <ul> |
| 35 | <li><strong>The code is the source of truth.</strong> Before changing a factual claim, check it against the code (<code>control.go</code>, <code>router.go</code>, <code>activator.go</code>, <code>mesh.go</code>, <code>controld.go</code>, <code>cloud.go</code>, <code>reaper.go</code>, <code>deploy/systemd/</code>) or the design documents (<code>docs/planet-scale.md</code>, <code>docs/instance-router.md</code>). Where this guide and the code disagree, fix the guide.</li> |
| 36 | <li><strong>Keep the register.</strong> 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.</li> |
| 37 | <li><strong>Keep the status badges honest.</strong> Anything not operable today must carry <span class="status partial">partially built</span> or <span class="status planned">designed, not built</span>, and aspirational behaviour belongs in a dashed <code>.roadmap</code> 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.</li> |
| 38 | <li><strong>Use the shared components</strong> rather than inventing new markup: <code>figure.cmd</code> for labelled command blocks, <code>ol.procedure</code> for step-by-step tasks, <code>.plain</code> / <code>.warn</code> / <code>.why</code> panels for recaps, cautions, and rationale, and <code>.status</code> badges. Examples of each are on every page.</li> |
| 39 | </ul> |
| 40 | |
| 41 | <h2 id="adding">Adding a page</h2> |
| 42 | <ol class="procedure"> |
| 43 | <li><p class="step-title">Copy an existing page as the template.</p> |
| 44 | <p>Keep the <code><head></code>, the <code>.frame</code>/<code>nav.side</code>/<code>main.content</code> skeleton, the header block, and the <code>div.sysmap</code>. Set <code>data-page</code> on <code><body></code> to the new file name.</p></li> |
| 45 | <li><p class="step-title">Add one entry to the <code>PAGES</code> list in <code>guide.js</code>, in reading order.</p> |
| 46 | <p>That single edit updates every page’s sidebar and previous/next links. Renumber the <code>num</code> fields and each page’s eyebrow (“Part NN of NN”) if the new page changes the ordering.</p></li> |
| 47 | <li><p class="step-title">Choose the system-map highlight.</p> |
| 48 | <p>Set <code>data-highlight</code> on the <code>div.sysmap</code> to the node keys the page covers (<code>members router instances services control updater bucket backup peer</code>, space-separated). If the page introduces a genuinely new component, add a node for it to <code>sysmapSVG</code> in <code>guide.js</code> so the map stays a true whole-system picture.</p></li> |
| 49 | </ol> |
| 50 | |
| 51 | <h2 id="checking">Checking your changes</h2> |
| 52 | <figure class="cmd"> |
| 53 | <figcaption>Run in the repository</figcaption> |
| 54 | <pre><code>node --check docs/planet-scale-guide/guide.js # the script must stay parseable |
| 55 | # then open the pages and click through: |
| 56 | open docs/planet-scale-guide/index.html # macOS; or any static file server</code></pre> |
| 57 | </figure> |
| 58 | <p>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.</p> |
| 59 | |
| 60 | <h2 id="authorship">Authorship marking</h2> |
| 61 | <p>Per the repository’s authorship convention (<code>CLAUDE.md</code>), 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.</p> |
| 62 | |
| 63 | <h2 id="publishing">Publishing to elevenmessenger.com</h2> |
| 64 | <p>The guide is published to <code>elevenmessenger.com/infrastructure/</code>, and this directory is the only source — nothing is ever hand-edited at the destination. Publishing is a <strong>local build</strong>, no GitHub Actions involved, in two steps:</p> |
| 65 | <ol class="procedure"> |
| 66 | <li><p class="step-title">Mirror this directory into the website repo.</p> |
| 67 | <p>Run <code>tools/sync-guide-to-website.sh <path-to-a-local-checkout-of-elevenmessenger/website></code>. It copies this directory into that separate, public repo’s <code>src/infrastructure/</code> (Eleventy passthrough-copies it to <code>/infrastructure/</code> unmodified — see that repo’s <code>.eleventy.js</code>), commits, and pushes the website’s <code>main</code>. It uses your own git credentials — no token to set up.</p></li> |
| 68 | <li><p class="step-title">Build and publish the website.</p> |
| 69 | <p>In that website checkout, run <code>./deploy.sh</code>: it builds the Eleventy site and force-pushes the output to the <code>gh-pages</code> 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 <code>README.md</code> § Deploy.</p></li> |
| 70 | </ol> |
| 71 | <div class="why"> |
| 72 | <span class="label">Why a local build, not a GitHub Action</span> |
| 73 | <p>This used to be automatic: a push to <code>main</code> touching this directory triggered <code>.github/workflows/sync-guide-to-website.yml</code>, which synced and deployed through the website’s own workflow. Both are now <strong>disabled</strong> — the project moved off GitHub Actions entirely (every binary already builds locally, and Actions was only ever publishing this site). The workflow files are kept in their trees, disabled, as the record of that approach; re-enabling them and flipping the website’s Pages source back to workflow-build is how you would restore auto-publish. (An earlier second copy served at <code>home.elevenmessenger.com/infrastructure/</code> is being retired.)</p> |
| 74 | </div> |
| 75 | |
| 76 | </div> |
| 77 | </main> |
| 78 | </div> |
| 79 | </body> |
| 80 | </html> |
| 81 | |
amadan