atlas

Why it exists

Every system in the constellation carries its own code, but the relationships between them — who builds on whom, which edge is a build dependency versus a published contract, where each repo sits in the stack — have no natural home in any single repo. Left to prose, that picture rots: a README claims an edge the code no longer has, a diagram lags the dependency graph, a copied convention drifts repo by repo. atlas owns exactly the things that concern two or more systems (or the whole) and have no single-repo owner. It is to build & relate what design is to look & read — orthogonal infrastructure under the stack, named plainly because it carries no substance of its own.

A concrete example

Each repo declares its place and its typed edges in its own atlas.json — build, runtime, or contract. atlas topology sync assembles those manifests plus the central registry into the generated topology/constellation.json, which in turn renders family.md and the constellation diagram (drawn in design's figure language). The hand-authored truth stays next to the code; the aggregate is derived, so it can't drift unseen. And the edges are checked: atlas manifest validate --reconcile confirms each declared build/contract edge against the repo's real package.json / go.mod / Cargo.toml, flagging any sibling depended on but not declared. A declared edge with no backing dependency yet is reported as intent-only, not an error; runtime edges aren't visible in build manifests and aren't reconciled.

What it unlocks

Because the topology is machine-readable and reconciled, everything downstream of it can be generated rather than maintained by hand — family.md, the constellation figure, and this site, which imports atlas's generated data directly so it can't fall out of sync. The substance systems — ontos, logos, horos, thesmos, and stele — declare their edges once, in place, and atlas keeps the stack view and the cross-repo decisions coherent across all of them. The CLI is zero-dependency, so npx github:Bitspark/atlas runs in any repo's CI with no install.

What's next

atlas is foundational and early (v0.1). The full topology pipeline is in place and every member repo runs manifest validate --reconcile in its own CI, but the cross-repo CI gates (reconcile, constellation-sync, figure-lint) are wired and still dormant until their read tokens are set. Next is machine-checked drift across repos once those tokens land.