# Map and glossary

> Where each question is answered, how data flows from the client to the game, and the words the docs use.

Page: https://polestar.guide/docs/contributors/docs-map (Polestar docs > Contributors)

Where each question is answered, grouped by who asks it: players who install
and go, guide authors who write community addons (other people's guides for
Polestar, each a separate addon), contributors who fix and build,
and maintainers who release. Paths are from the repository root.

## The docs

| Doc | Reader | What it answers |
|---|---|---|
| [README.md](https://polestar.guide/docs/players/quick-start) | players, everyone | What Polestar is, how to install it, what it does, where to go next |
| [CHANGELOG.md](https://polestar.guide/docs/reference/changelog/0-2-6) | players, guide authors, contributors | What changed in each release, under "For players", "For guide authors" and "For contributors"; what is merged but not released yet is in `changes/` ([changes/README.md](https://github.com/fitzforge/polestar/blob/next/changes/README.md)) |
| [docs/GUIDE_PACKS.md](https://polestar.guide/docs/players/community-guides) | players, guide authors | What a community addon is and is not, how to tell one from Polestar's own addons, installing one, turning it on or off, who supports it; for authors, the steps from `new` to publishing, what the tools require and what we ask of you. The in-game Community guides page links here |
| [docs/GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet) | guide authors | The guide format on one page: every header line, goal and condition, with what it does and a short example |
| [docs/GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format) | guide authors | The `.guide` language in full: header, steps, goals, conditions, what the compiler fills in, validation, a cookbook |
| [docs/PACKS.md](https://polestar.guide/docs/authors/handbook) | guide authors | The full handbook: how to write, test, publish and update a community addon; every problem the tools or the game can report, with its fix |
| [docs/PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format) | guide authors, tool builders | The contract between a community addon and Polestar: `pack.json`, the addon the compiler writes, the rules Polestar enforces, import strings, versioning |
| [LICENSE-EXCEPTION.md](https://polestar.guide/docs/reference/license-exception) | guide authors | The permission to distribute a compiled community addon or an import string under terms of your choice |
| [CONTRIBUTING.md](https://polestar.guide/docs/contributors/contributing) | players, guide authors, contributors | Ways to help; how to report a wrong step; how to fix a guide; setting up; code changes; which branch a pull request goes to; using an AI agent; commits and pull requests; the license of contributions |
| [AGENTS.md](https://github.com/fitzforge/polestar/blob/next/AGENTS.md) and [skills/](https://github.com/fitzforge/polestar/tree/next/skills) | contributors' coding agents | AGENTS.md points every agent to its skill: `polestar-contributing` (branches, generated files, changelog fragments, what a pull request must not do, posting on issues), `polestar-triage` (checking a report before agreeing it is a bug), `polestar-guide-fix`, `polestar-guide-pack` |
| [SECURITY.md](https://polestar.guide/docs/reference/security) | everyone | How to report a security problem privately, and what counts as one |
| [docs/TRANSLATING.md](https://polestar.guide/docs/authors/translating) | translators, contributors | The languages and their status, the locale file and how to fill it, formats, the glossary, the `i18n` commands, adding or reviewing a language |
| [docs/ARCHITECTURE.md](https://polestar.guide/docs/contributors/architecture) | contributors | The contract between the addon's modules, the compiled guide data, the toolchain and the tests |
| [addon/README.md](https://polestar.guide/docs/contributors/addon) | contributors | Which addon is which, the modules in load order with each file and its public table, where a hub screen lives, the generated files inside `addon/` |
| [tools/README.md](https://polestar.guide/docs/contributors/tools) | contributors, maintainers | The commands by group, the `tools/lib` folders, every generated file with its command and inputs, how to tell it is stale, the rebuild order after a data change |
| [tests/README.md](https://polestar.guide/docs/contributors/tests) | contributors | The test layers, the fake client, the helpers, how to run one test, what needs local data |
| [docs/SUITE.md](https://polestar.guide/docs/contributors/suite) | contributors | The modules and their scope, which other addons and sites Polestar reads, the data layer, the in-game packs |
| [docs/SIMULATION.md](https://polestar.guide/docs/contributors/simulation) | contributors | The route simulator: world model, character model, search, calibration, results |
| [docs/DESIGN.md](https://polestar.guide/docs/contributors/design) | contributors | The design system: who the windows are for and what they must do, then colour, type, layout and component tokens |
| [docs/NAV_QA.md](https://github.com/fitzforge/polestar/blob/next/docs/NAV_QA.md) | contributors, maintainers | The pathing checks: every problem reported against Shortest Path Forever that touches what Polestar uses from it, the check Polestar holds itself to and the test or in-game step that enforces it |
| [docs/RELEASING.md](https://polestar.guide/docs/contributors/releasing) | maintainers | What ships, setting the version, the feature release steps, patch releases from a `hotfix/` branch, release candidates |
| [docs/curseforge/README.md](https://polestar.guide/docs/contributors/releasing/curseforge) | maintainers | The CurseForge listing: the summary, the project settings, what to upload where, and the description to paste ([description.md](https://github.com/fitzforge/polestar/blob/next/docs/curseforge/description.md)) |
| [THIRD_PARTY.md](https://polestar.guide/docs/reference/credits) | guide authors, maintainers | Where every input comes from, its license, and what may enter the repository or a release |

`docs/preview/` holds renders of the addon's windows (`node tools/polestar.js
preview`); `docs/assets/` holds the README's art and screenshots.

## The moving parts

Data flows from the game client and local sources into reference data, from
there into the data addons and the compiled guides, and from `addon/` into
the game. The Recorder sends play back into the reference data; the
simulator turns reference data into route drafts for the guides.

*(Diagram: Map and glossary, https://github.com/fitzforge/polestar/blob/next/docs/docs/media/diagrams/contributors-docs-map.svg)*

`data/forever`, `data/recordings` and the local data addons stay on the
machine that built them; [tools/README.md](https://polestar.guide/docs/contributors/tools) lists every
generated file, whether it is committed, and the order to rebuild in.

## Glossary

- **Hub**: Polestar's main window: a rail of sections (Guides, Lookup, Dungeons, Rares) with Options at its foot (`UI/Picker.lua`).
- **Guide menu**: the hub's Guides section, where a player picks a guide.
- **Guide window**: the small window that shows the current step and its goals while playing (`UI/GuideFrame.lua`).
- **Guide**: one route, written as a `.guide` file and compiled to Lua; its id reads like `forever/alliance/human/01-elwynn-forest`.
- **Step**: one stop in a guide: a title, optional conditions and tip, and at least one goal.
- **Goal**: one thing to do in a step, as a verb and its arguments (`accept 783`, `kill`, `goto`, `turnin`...).
- **Pack**: an addon of guides for Polestar, built by the compiler from a folder with a `pack.json` (the folder is a pack too); Polestar's own is `Polestar_Guides` (pack id `guides`). **Community addon**: every other pack, a separate addon made and supported by its author, listed under Community guides ([GUIDE_PACKS.md](https://polestar.guide/docs/players/community-guides)).
- **Reference data**: the game facts in `data/forever/*.json` (quests, NPCs, objects, items, zones, map frames and more) that the compiler and the data builds read; built locally by `data build`.
- **Data addon**: a companion addon that carries data, not code, mostly loaded on demand: `Polestar_QuestDB`, `Polestar_ItemDB`, `Polestar_Codex`, `Polestar_Travel`.
- **Codex**: Lookup's database of items, mounts, pets, recipes, NPCs, rares, quests, zones, dungeons and treasures, with where each comes from (`codex build`, the `Polestar_Codex` addon).
- **QuestDB**: the quest database behind quest markers and tooltips (`questdb build`, the `Polestar_QuestDB` addon).
- **ItemDB**: item stats for the gear advice (`itemdb build` and `gear build`, the `Polestar_ItemDB` addon).
- **Recorder**: the optional `Polestar_Recorder` addon that records play; `record import` turns its sessions into `data/recordings`.
- **Playground**: the real addon running in a browser against a simulated world (`node tools/polestar.js play`).
- **Simulator**: the route model and search that finds and scores leveling routes (`node tools/polestar.js sim`, [SIMULATION.md](https://polestar.guide/docs/contributors/simulation)).
- **Playtest**: playing a pack's guides to the end in the real addon, once per class they branch on (`node tools/polestar.js playtest`).

---

Next page: [Architecture](https://polestar.guide/docs/contributors/architecture.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt