1# Atlas23Atlas is an offline map explorer built around a file format. A world — a game's4map, a city's open data, Mars — travels as one self-contained `.atlas` bundle:5its manifest, its features, its raster tile pyramids and its icons in a single6zip archive. Drop a bundle into the library and the volume appears; drop in a7newer build of the same volume and it takes over. No sidecars, no CDN, no8runtime network of any kind, ever.910Two things ship from this repository:1112- **`atlas`** — the pipeline and the server. `crawl` captures what a publisher13 serves, `tiles` derives pyramids, `compose` writes bundles, `enrich` folds14 several readings of a volume together, `measure` scores them, `workbench`15 serves the operator's pages, `serve` serves the application headlessly, and16 `dev` is the loop for working on it.17- **Atlas** — the desktop application: the same application in a window.1819```sh20go build ./cmd/atlas # the CLI21make desktop # the desktop app (macOS; see .github/workflows/release.yml)22make serve-static # the application over HTTP, with the seam mounted23```2425The desktop application ships with one included volume — Earth, NASA's Blue26Marble base map as an ordinary `.atlas` bundle — installed into the library at27first launch, so a fresh install opens onto a world28([`included/README.md`](included/README.md) carries the provenance and the29regeneration recipe).3031The library lives under the application's own data directory —32`~/Library/Application Support/dev.felinestatemachine.atlas/bundles` on macOS,33`%AppData%\dev.felinestatemachine.atlas\bundles` on Windows,34`~/.config/dev.felinestatemachine.atlas/bundles` on Linux. `ATLAS_BUNDLES_DIR`35points either the CLI or the desktop app somewhere else; `atlas compose36-bundles DIR` writes a registry elsewhere without touching the library at all.3738## Released builds3940Tagged releases carry the CLI for five targets and the desktop application for41Windows (x64), macOS (Apple Silicon) and Linux (x64). Two platform notes:4243- **macOS**: the app is unsigned. After unzipping, clear the quarantine with44 `xattr -dr com.apple.quarantine Atlas.app`, or approve it under System45 Settings → Privacy & Security → "Open Anyway".46- **Linux**: the binary links GTK 3 and WebKitGTK 4.1 at runtime47 (`libgtk-3-0`, `libwebkit2gtk-4.1-0`) — present on Ubuntu 24.04+, Debian 13,48 and recent Fedora.4950## The shape of it5152```53format/ THE CENTRE. The .atlas container, manifest, ATLASLOC codec,54 stamps, registry, validation, and the semantic conventions.55 Pure Go, standard library only, importable by anyone.56internal/57 generate/ Capture and composition: crawl, five sources, tiles, compose.58 enrich/ Merge, national layers, standard icons, lenses, maturity.59 app/ The hypermedia application: one pure http.Handler, HTMX 4.60 workbench/ Scores, build diffs, source cards, pipeline operations.61analysis/ TypeScript: the cell systems (geohash, S2) behind one contract.62render/ TypeScript: the rendering seam. Deletable, and deleted in the63 sense that matters — nothing imports it, and the application64 builds, serves and works with its assets absent.65testdata/ The committed corpus: real extractions with public66 provenance (see testdata/corpus/README.md).67tests/, tools/ The test trees that cannot live with their packages, and68 the enforcement commands — depcheck, which enforces every69 boundary named above, testgate and corpussmoke.70main.go The desktop shell: ~300 lines of host wiring around the71 handler, and the whole of what a window costs.72```7374## Documentation7576[`docs/`](docs/) is the system, written down. Read in this order:77[`format.md`](docs/format.md) is the centre;78[`generate.md`](docs/generate.md) and [`enrich.md`](docs/enrich.md) are how a79bundle comes to be; [`app.md`](docs/app.md) is what serves it;80[`render-seam.md`](docs/render-seam.md) and81[`analysis.md`](docs/analysis.md) are what pictures it;82[`workbench.md`](docs/workbench.md) is the operator's view;83[`logging.md`](docs/logging.md) is how everything narrates itself;84[`testing.md`](docs/testing.md) is how it is judged; and85[`decisions/`](docs/decisions/) is why any of it is shaped this way.86[`docs/README.md`](docs/README.md) is the map.8788## Verification8990```sh91npm ci92make test # vet, every Go test skip-proof, both TypeScript lanes, depcheck93make test-e2e # the application in a real browser, over the committed corpus94```9596`make test` is the whole required surface, and it is what CI runs on Linux,97macOS and Windows (`.github/workflows/ci.yml`).98[`docs/testing.md`](docs/testing.md) is the map: the layers, what tests are99made of, where they live, and the bar for a new one.100101## History102103Atlas was rewritten from a clean room in 2026 ([issue104#5](https://github.com/FelineStateMachine/atlas/issues/5)). The implementation105it replaced is archived, checkout-able, whole and working, at the tag106**`golden-reference`** (mirrored at `archive/golden-reference`), and the107behavioral differences accepted against it are [decision10818](docs/decisions/0018-divergences-from-the-reference.md). Nothing on this109branch imports it — `tools/depcheck` refuses the edge — and no file here cites110its comments as documentation.