1# Atlas23Atlas is an offline map explorer built around a file format. A world travels as4one self-contained `.atlas` volume: a schema-described semantic graph, packed5typed features, raster pyramids, presentation and assets. Drop a volume into6the library and it appears; drop in a newer build and it takes over. No7sidecars, CDN, or runtime network is required.89Two things ship from this repository:1011- **`atlas`** — the authoring tool and server. `build` turns one portable12 `.atlas-project` manifest directly into native vNext, `workbench` provides the13 visual authoring/build surface, `measure` scores libraries, `serve` hosts the14 application headlessly, and `dev` is the development loop.15- **Atlas** — the desktop application: the same application in a window.1617```sh18go build ./cmd/atlas # the CLI19make desktop # the desktop app (macOS; see .github/workflows/release.yml)20make serve-static # the application over HTTP, with the seam mounted21```2223The desktop application ships with one included volume — Earth, NASA's Blue24Marble base map as an ordinary `.atlas` bundle — installed into the library at25first launch, so a fresh install opens onto a world26([`included/README.md`](included/README.md) carries the provenance and the27regeneration recipe).2829The library lives under the application's own data directory —30`~/Library/Application Support/dev.felinestatemachine.atlas/bundles` on macOS,31`%AppData%\dev.felinestatemachine.atlas\bundles` on Windows,32`~/.config/dev.felinestatemachine.atlas/bundles` on Linux. `ATLAS_BUNDLES_DIR`33points either the CLI or desktop app somewhere else; `atlas build -bundles DIR`34writes a library elsewhere without touching the application library.3536## Released builds3738Tagged releases carry the CLI for five targets and the desktop application for39Windows (x64), macOS (Apple Silicon) and Linux (x64). Two platform notes:4041- **macOS**: the app is unsigned. After unzipping, clear the quarantine with42 `xattr -dr com.apple.quarantine Atlas.app`, or approve it under System43 Settings → Privacy & Security → "Open Anyway".44- **Linux**: the binary links GTK 3 and WebKitGTK 4.1 at runtime45 (`libgtk-3-0`, `libwebkit2gtk-4.1-0`) — present on Ubuntu 24.04+, Debian 13,46 and recent Fedora.4748## The shape of it4950```51format/ THE CENTRE. The .atlas schema, packed typed tables,52 content-addressed blobs, registry and semantic conventions.53 Pure Go, standard library only, importable by anyone.54internal/55 authoring/ Manifest, adapters, evidence cache, semantic assembly, publish.56 generate/ Retired pipeline retained for fixture migration and tests.57 enrich/ Legacy enrichment plus the current maturity measurement.58 app/ The hypermedia application: one pure http.Handler, HTMX 4.59 workbench/ Scores, diffs, manifest authoring, plans, builds and handoff.60analysis/ TypeScript: the cell systems (geohash, S2) behind one contract.61render/ TypeScript: the rendering seam. Deletable, and deleted in the62 sense that matters — nothing imports it, and the application63 builds, serves and works with its assets absent.64testdata/ The committed corpus: real extractions with public65 provenance (see testdata/corpus/README.md).66tests/, tools/ The test trees that cannot live with their packages, and67 the enforcement commands — depcheck, which enforces every68 boundary named above, testgate and corpussmoke.69main.go The desktop shell: ~300 lines of host wiring around the70 handler, and the whole of what a window costs.71```7273## Documentation7475[`docs/`](docs/) is the system, written down. Read in this order:76[`format.md`](docs/format.md) is the centre;77[`authoring.md`](docs/authoring.md) is how a volume is built;78[`app.md`](docs/app.md) is what serves it;79[`render-seam.md`](docs/render-seam.md) and80[`analysis.md`](docs/analysis.md) are what pictures it;81[`workbench.md`](docs/workbench.md) is the operator's view;82[`logging.md`](docs/logging.md) is how everything narrates itself;83[`testing.md`](docs/testing.md) is how it is judged; and84[`decisions/`](docs/decisions/) is why any of it is shaped this way.85[`docs/README.md`](docs/README.md) is the map.8687## Verification8889```sh90npm ci91make test # vet, every Go test skip-proof, both TypeScript lanes, depcheck92make test-e2e # the application in a real browser, over the committed corpus93```9495`make test` is the whole required surface, and it is what CI runs on Linux,96macOS and Windows (`.github/workflows/ci.yml`).97[`docs/testing.md`](docs/testing.md) is the map: the layers, what tests are98made of, where they live, and the bar for a new one.99100## History101102Atlas was rewritten from a clean room in 2026 ([issue103#5](https://github.com/FelineStateMachine/atlas/issues/5)). The implementation104it replaced is archived, checkout-able, whole and working, at the tag105**`golden-reference`** (mirrored at `archive/golden-reference`), and the106behavioral differences accepted against it are [decision10718](docs/decisions/0018-divergences-from-the-reference.md). Nothing on this108branch imports it — `tools/depcheck` refuses the edge — and no file here cites109its comments as documentation.