docs: an edge site is a Thing, not a leaf_nodes record

[skeeeon]

Follows stone-age-io/platform, which dropped the leaf_nodes collection and the leaf-sync binary, and stone-age-io/agent, which absorbed the latter.

leaf-nodes.md is rewritten, not edited

It used to describe a collection, a per-site binary and a config mirror. All three are gone. The filename stays so inbound links survive.

What replaces it is one route — GET /api/me/leaf-config — plus the reasons the alternatives were rejected, which is the part worth having in docs:

• no gateway flag, because thing_types already says what a device is and a second marker is a second thing to get wrong;
• no stored domain, because it was a second copy of the code that could disagree with it, and when it did the site simply stopped appearing;
• no config mirror, because nothing consumed the mirrored rows.

Two things were rescued from the old cmd/leaf-sync README before it was deleted, since they existed nowhere else:

• The two operator-mode directives a generated nats-leaf.conf must carry — a leaf remote's account key, and the $SYS account JWT in resolver_preload, without which the server dies before JetStream starts — and the distinction between preloading the $SYS account JWT, which grants nothing, and a $SYS user credential, which is never served.
• One writer per bucket for the digital twin, with the number that made the case: ~170k writes to a single key in 300ms when both ends wrote one bucket. It does not pick a loser on a conflict, it oscillates.

New in §7: site connectivity comes from $SYS.REQ.ACCOUNT.PING.CONNZ, asked by the console over its own in-account connection, with the publish-DENY-beats-ALLOW trap written down beside it. That one surfaces as a bare request timeout with the real reason arriving only on the async error handler, so it is the failure someone re-tightening a NATS Role would otherwise spend a day on.

The rest of the pass

authorization.md §6 rewritten as "Gateways and the Edge", keeping the point that mattered: the route gates on nothing, because everything it serves is public trust material or the caller's own credential — so the blast radius of a leaked edge credential is a fixed list of named fields rather than a consequence of rules that change for unrelated reasons. The leaf_nodes rows come out of the role table.

agent.md loses the "not to be confused with leaf-sync" note and gains the four edge capabilities. It also corrects two claims that were already stale before this change: it said the Agent "neither fetches nor manages Nebula" and "does not manage the Nebula interface". Both have been untrue since the overlay feature landed.

health-metrics.md §5 rewritten for the agent's agent_edge_* series and its two checks (not four), with the alert expressions updated to match.

configuration.md, connectivity.md, index.md, getting-started.md, operations.md, platform-ui-entities.md, overview.md, platform-layers.md updated for the platform: config block, auth.type: "platform", and platform.sync_interval. operations.md's failure-mode and upgrade-order tables now say that restarting the agent on a site bounces the leaf server only if nats.server_config is set.

ADR 0002 is annotated, not edited

It cites leaf_nodes as the precedent for freezing code. That is what was argued at the time, and an ADR is a record of that argument — rewriting it would erase the decision it exists to document. A status note points at things.code as today's precedent instead.

Verification

All internal links resolve across 21 files — target file exists, and every #anchor matches a heading slugified the way mkdocs (python-markdown's toc extension) does. That check caught two broken anchors, one of them written during this pass.

---

Merge with platform: stone-age-io/platform#11 and agent: stone-age-io/agent#4 — the three land together.

🤖 Generated with Claude Code