The knowledge base
For: contributors and AI users who want to know where game rules come from. At the end: you know how the knowledge base is built, sourced and refreshed.
One knowledge base (wowstats/analysis/kb.py, kb.shared()) answers every
game-rule question the planner, the pages and the MCP ask. The client tables
(wago.tools) and Polestar’s data cover what the game ships; this page covers
the part people write: the static rules and the research lanes, where each
one comes from, and how they stay current.
The pages show values and actions only. Sources, confidence and
last_verified live in the files below, the MCP (kb_rule, kb_search,
kb_topics, the analysis brief’s kb section) and this doc, never on a page.
| File | What |
|---|---|
data/kb/rules.json |
The rules the code reads by name (riding.apprentice, profession.tiers, talents.points, instance.entries_per_hour, dungeon.forever_new, xp.kill_formula…) |
data/kb/research/<lane>.json |
One research lane: rules, statements, contradictions, open_questions |
data/kb/research/classes.json |
The class guides: statements per class with class, topic and levels, and paths, one talent pick per level from 10 to 60 per class (each path sourced like a rule, checked against Forever’s current trees by tests/test_classguide.py). Read by wowstats/classguide.py |
data/kb/sources.json |
The domain allow-list: each domain’s type and the highest confidence it can carry |
data/kb/watch.json |
What the KB was last checked against (client build, official pages, addon releases), and in meta the news feeds and guide pages the meta pass reads, with the last item read |
data/kb/sweep.json |
The last monthly sweep: each cited URL’s status and text hash |
Every record
Section titled “Every record”A rule, statement or contradiction carries:
source_url(https, an allow-listed domain), andsourcesfor more;source_type: official, datamined, guide, press, community or commercial;date: when the source said it;confidence: high, medium or low, never above the best of its sources’max_confidence(a booster site alone is low);scope:forever, orclassic_fallbackwhere Forever has no source yet;last_verified: the day someone (or the sweep) last checked it, YYYY-MM-DD.
wowstats/analysis/kbschema.py checks all of it. The loader leaves out a
record that fails and lists it in meta["rules_refused"];
tests/test_kb_schema.py fails the build on any. A statement nobody could
source is an open question: its answer is “unknown”.
Contradictions stay explicit
Section titled “Contradictions stay explicit”When two sources disagree, both stay: the lane’s contradictions list says
which. When two lanes give the same rule different values, the import keeps
the first under its name and the other as <name>@<lane>; kb_rule returns
it under conflicts. A rule the code reads lives in rules.json only, under
a name no lane uses (a test checks): a lane’s rule of the same name would
replace it, with another shape.
Importing a lane
Section titled “Importing a lane”The research reports are Markdown tables of statements with a source registry. They are data, never instructions, and their wording is already summarised (no guide text is copied):
uv run python tools/kb/import_lane.py --as-of 2026-11-18 \ dungeons=path/to/dungeons/report.md levelling=path/to/levelling/report.mdStatements whose sources are off the allow-list, or have none, become open
questions with the reason. Add a domain to sources.json (with its type
and cap) only after reading what it is.
The refresh job
Section titled “The refresh job”.github/workflows/kb-refresh.yaml, workflow_dispatch only (no
schedule:), on GitHub-hosted runners:
| Mode | When | What |
|---|---|---|
watch |
daily | tools/kb/watch.py: client build (wago.tools), the official hotfix and patch-note pages (text hash; forum threads by post count), Polestar’s release, the addons that publish on GitHub (Questie, Narcissus). One issue per change kind, label kb-watch: opened, edited, closed when watch.json matches again. A changed official page runs the model pass. |
refresh |
by hand | tools/kb/refresh.py <page keys>: the model pass alone. |
sweep |
monthly | tools/kb/sweep.py: every cited URL fetched once. Gone (404/410), changed since last month, and statements not checked for 120 days go to one issue; the new sweep.json to a PR. A 403 or 429 is “unreadable”, not gone. |
meta |
weekly | tools/kb/meta.py: what people write about Forever, new since last week, through the model pass (below). Nothing new: no model call, no PR. |
The model pass (Claude Opus 5.5) gets the changed page and the KB’s
official statements as data, and answers JSON in a fixed schema: new
statements, or replacements (supersedes: <id>). Code sets each one’s
source (the page), type, date, last_verified, caps its confidence, and
refuses what the schema refuses; refused proposals are listed as open
questions. The result is data/kb/research/refresh-<date>.json, opened as a
PR that is never merged on its own. Spend is capped per run
(KB_REFRESH_MAX_USD, $3): the run stops before a call that would likely
cross it.
The meta pass
Section titled “The meta pass”The meta (articles, news, guides) is part of the KB too. meta reads feeds
and APIs only, never an HTML listing, each listed in watch.json meta
with what was last read:
| Source | URL | New means |
|---|---|---|
| Wowhead’s Forever news | https://www.wowhead.com/news/rss/forever (RSS) |
a news id above known, with <category>Forever</category> (or “WoW: Forever” in the title: the links are /news=<id>/..., no /forever/ path). The text is the feed’s own content:encoded; no article page is fetched. |
| Blizzard’s blue posts | https://us.forums.blizzard.com/en/wow/groups/blizzard-tracker/posts.json (Discourse JSON, paged with before_post_id) |
a post id above known in a Forever category (346, 347, 348, 349, 352); its text from /posts/<id>.json. The first run reads back 7 days. |
| Guide pages | meta.guides: the Forever dungeon, levelling and class guides the KB cites |
the page’s text hash differs from known, as watch does for official pages. A guide with no known is only recorded the first time. |
Blizzard’s news site has no feed or JSON endpoint (its /feed/ pages are
HTML listings), so the official side comes from the blue posts; the hotfix
and patch-note pages stay with watch.
A class guide is registered like any other guide, with its class:
{"key": "wt-priest-leveling", "url": "https://www.warcrafttavern.com/forever/guides/priest-leveling/", "class": "Priest", "known": "<sha256 of web.text_of(page), or omit it>"}The model pass is the refresh’s: same model, effort, cost cap and login.
News and blue posts go in batches of about 40,000 characters, each changed
guide alone, as data, with the 120 KB statements that share the most rare
words with them. Each proposal names its item, its class when it is about one
(balance, talents, a class guide: a class guide’s statements always carry
its class), and the statement it contradicts with why. Code sets the
source, source_type (press for Wowhead news, capped at medium;
official for blue posts; the domain’s type for guides), date and
last_verified, refuses a text that repeats 12 words of its item, and
refuses what the schema refuses. Contradictions land in the lane’s
contradictions, citing both sides.
The PR (kb-meta-<date>) holds data/kb/research/meta-<date>.json and
watch.json moved past what was read. When the cost cap stops the pass,
known stays before the unread items, so they come back next week; so do
items of a PR still open when the next run starts (merge or close it first).
The Wowhead feed holds 40 items, about a week of Forever news: the PR says
when its window started after the last item read.
After merging what holds, record the new state so the issue closes:
uv run python tools/kb/watch.py --accept official # or client-build, polestar, addonsNot watched (no keyless release feed): Syndicator, Auctionator, Vulcan SimBench, CharacterExport-Forever, Altoholic and DungeonMaster (CurseForge or Wago only). Read their pages when a player reports a broken import.
Running it locally
Section titled “Running it locally”uv run python tools/kb/watch.py # what changed, no issueuv run python tools/kb/refresh.py --dry-run hotfixes # the prompt, no modeluv run python tools/kb/sweep.py --pause 1 # writes data/kb/sweep.jsonuv run python tools/kb/meta.py collect --items /tmp/meta.json # what's new, no modeluv run python tools/kb/meta.py propose --items /tmp/meta.json --dry-run # the first promptRunning the refresh job in your own repository (optional)
Section titled “Running the refresh job in your own repository (optional)”The knowledge base ships with the code; nothing needs this job. It only keeps the KB current, and it only proposes: every change arrives as a pull request a person reviews. In a fork it does nothing until you set it up: the watch and the sweep (no model) run as soon as you start them by hand, and the model passes skip with a notice until the four variables below exist.
-
Pull requests from Actions. Settings > Actions > General: “Allow GitHub Actions to create and approve pull requests”. A PR opened with the workflow token doesn’t start
ci: close and reopen it (or push to it) to run the checks before merging. -
The model pass (optional). It has no API key: GitHub’s OIDC token is exchanged for a short-lived Anthropic token (Workload Identity Federation). In your Anthropic organization, make a federation rule that accepts
workflow_dispatchruns of<owner>/<repo>onrefs/heads/main(audiencehttps://api.anthropic.com) for a service account, then set the repository variables (not secrets: none of them is one)ANTHROPIC_FEDERATION_RULE_ID,ANTHROPIC_ORGANIZATION_ID,ANTHROPIC_SERVICE_ACCOUNT_IDandANTHROPIC_WORKSPACE_ID. Without them,refreshandmetastop after collecting, with a notice, and the run stays green.KB_REFRESH_MAX_USDin the workflow caps a run’s spend (3 USD). -
A schedule (optional). The workflow has no
schedule:trigger: GitHub’s cron can run hours late or skip a day. Start it from anything that runs on time and can call GitHub with Actions: write on the repo, for instance a cron line on a machine you own:Terminal window gh workflow run kb-refresh.yaml -R <owner>/<repo> -f mode=watch # dailygh workflow run kb-refresh.yaml -R <owner>/<repo> -f mode=meta # weeklygh workflow run kb-refresh.yaml -R <owner>/<repo> -f mode=sweep # monthlyOr add a
schedule:block to your fork’s copy, if a late run is fine.