# Atlas and geographic knowledge v1

Public geographic facts, independent of the auction market map. Website and MCP share
`shared/src/atlas.ts` and `cloud/src/atlas.ts`; consumers must preserve source and compatibility
labels. No account, character, quest progress, seller, bidder or uploader data belongs here.

## Catalogue

`GET /api/v1/atlas` returns `AtlasCatalogue` (the strict Zod schema is authoritative):

```ts
{
  v: 1,
  version: string, // client build + deterministic content digest; changes whenever facts change
  product: "wow_classic_beta",
  build: string, // pinned Forever 1.60.x.n
  sources: AtlasSource[],
  maps: AtlasMap[],
  places: AtlasPlace[],
  quests: AtlasQuest[],
  acquisitions: AtlasAcquisition[],
  coverage: {
    quests: "unavailable" | "partial" | "available",
    acquisitions: "unavailable" | "partial" | "available",
    artwork: "schematic-only" | "licensed"
  }
}
```

`AtlasSource = {id,title,url,revision,license,rights,evidence,note}`. `rights` is
`client-metadata | open-license | first-party`, a provenance classification, **not** a license
grant. `evidence` contains `{kind:client-table|historical-source|in-game,reference,build?}`.
DB2 sources carry the exact source CSV SHA-256 in `revision` and `reference`.

Every record carries `provenance = {sourceIds:string[], compatibility, referenceBuild:string}`:

- `unverified-forever`: source-confirmed facts from this pinned Forever client; live behavior
  and availability have not been observed
- `historical-reference`: historical evidence; may differ on Forever, always visibly labeled
- `verified-forever`: live, in-game evidence for the catalogue's exact build is required

The validator rejects missing source/map/place references, duplicate IDs, parent cycles,
mismatched Forever builds, unsupported verification claims and unreferenced drop chances.
No fabricated rates. `dropRate:null` means unknown; it never means zero.

`AtlasMap = {id,name,parentId:number|null,kind:world|continent|zone,width,height,rects,provenance}`.
`id` is a **UiMap ID**, not a world-instance ID. Pixel dimensions are coordinate frame dimensions,
not a promise that licensed art exists. `rects` contains one `{instanceId,left,top,width,height}`
per world instance. Map rectangles describe map extents, not zone borders or coastlines.

`AtlasPlace = {id:string,name,mapId,x,y,kind,provenance}`. Kinds: `area`, `quest-start`, `quest-end`,
`objective`, `vendor`, `gathering`, `dungeon`. **Area labels are approximate label anchors** from
WorldMapOverlay hit boxes, not exact entrances, NPC spawns, quest givers or objectives.

`AtlasQuest = {id,name,level:number|null,placeIds,prerequisiteIds,rewardItemIds,provenance}`.
Prerequisite IDs may name quests outside the catalogue; they are references, not implied facts.
`AtlasAcquisition = {itemId,kind:quest-reward|vendor|drop|gathering|crafting,questId?,placeIds,
dropRate:null|{fraction:0..1,evidenceReference},provenance}`. Quest rewards require a recorded quest.

## Coordinates

Map x/y are finite fractions 0..1 from the top left. World coordinates are yards: X north,
Y west. `X = top - y*height`, `Y = left - x*width`; the inverse is
`x = (left-Y)/width`, `y = (top-X)/height`. Each rect is a different world instance.
Project only between maps sharing an instance **and reference build**. Azeroth has separate
instance transforms; do not merge continents into one world coordinate frame. Historical
coordinates retain their reference build until a documented conversion is available.

## Search and locations

All endpoints are anonymous public reads through the normal API rate limit and route gate.
Unsupported methods return 405. Invalid queries return 400 `bad_query`. Catalogue responses
have an ETag (`"atlas-<version>"`), conditional reads return 304, and reads cache for five minutes.
Search and locations do not reuse the catalogue ETag across different queries.

`GET /api/v1/atlas/search?q=<up to 120 chars>&kind=<map|place|quest|item>&limit=<1..50>`:

```ts
{
  v: 1, version, build, coverage, sources,
  query: string, total: number,
  hits: [{kind,id:number|string,name,mapId:number|null,placeId:string|null,
          x:number|null,y:number|null,provenance,url:string}]
}
```

Search is case/accent insensitive. Empty queries return no hits. `total` is before the limit.
`url` is a relative website deep link. Item acquisition search currently identifies items by
ID; item display names still come from the existing client-table item catalogue.

`GET /api/v1/atlas/locations?itemId=<base item ID>` or `?questId=<quest ID>` or
`?mapId=<UiMap ID>`. A map filter can accompany the item or quest. Item and quest together are
invalid. IDs must be positive safe integers.

```ts
{
  v: 1, version, build, coverage, sources,
  query: {itemId:number|null,questId:number|null,mapId:number|null},
  places: AtlasPlace[], quests: AtlasQuest[], acquisitions: AtlasAcquisition[],
  reason: null | "not-recorded"
}
```

No recorded acquisition returns empty arrays, `reason:"not-recorded"`, and the catalogue
coverage; never claim an item cannot drop or a quest does not exist. `mapId` alone lists area
labels. When filtering item/quest records by map, the returned `places` are filtered; quest
and acquisition records retain their original `placeIds` and provenance.

Runtime: `atlasCatalogue()`, `searchAtlas({q,kind?,limit?})`, `atlasLocations({itemId?,questId?,mapId?})`
from `cloud/src/atlas.ts`. The parent plugin owns MCP tools and its own recipe/questline references.
It must not substitute questline title associations for atlas geographic evidence.

## Website links and assets

`/atlas?map=<UiMap ID>&place=<place ID>` selects a recorded label. Camera links use
`x=<0..1>&y=<0..1>&zoom=<Leaflet CRS.Simple zoom, -4..8>`. `quest` and `item` select the corresponding
knowledge panel. Unknown IDs are reported; they never invent a position.

The catalogue describes an original geometric index of client map extents. Its
`coverage.artwork` field describes that geometry catalogue, not website asset availability.
The website separately loads `/atlas-art/<catalogue.build>/manifest.json` and only uses artwork
whose build and map dimensions match. Parchment tiles use
`/<mapId>/parchment/<z>/<x>_<y>.webp` relative to that manifest, with 256px tiles and native zoom 0.
Artwork is on by default, with a user toggle and the geographic index retained underneath.
Missing tiles show a status message; missing manifests leave the geographic index available.

The website packages Blizzard's client world-map artwork as attributed fansite illustrations,
following Jared's request to show map images (2026-11-04). This supersedes the original
local-review-only product decision. The images remain Blizzard proprietary artwork, not part
of the project's open-source license. No VMaNGOS data, Questie databases or third-party market
facts are shipped. Source URLs and SHA-256 hashes accompany the pinned asset manifest.
Regenerate using `node scripts/atlas/private-art.mjs --website --all`; without `--website`,
the extractor still writes to ignored local cache for private review. Website extraction ships
parchment only; satellite/minimap extraction stays local.
